Atomic CRM: self-hosted CRM for contact and deal management

Atomic CRM's CRM scope and target users

Atomic CRM addresses the operational part of customer relationship management: storing contacts, recording follow-up work, documenting interactions, and following deals through a sales pipeline. The intended audience is not limited to developers. The README presents a usable CRM for small sales or service teams that want an application they can inspect, fork, customize, and host, while the repository layout also makes it suitable for engineering teams that need to extend the frontend or backend.

The feature set centers on contacts as the shared record. A team can create tasks and reminders, add notes, capture email communications, and review an aggregated activity history. Deals are displayed in a Kanban pipeline, which makes stage movement a central workflow rather than leaving sales status in separate notes or spreadsheets. Import and export are also included for moving contacts into and out of the system.

Access is not limited to a single local authentication method. The README names Google, Azure, Keycloak, and Auth0 as supported login providers. Custom fields, theme changes, component replacement, and an API are advertised as extension points. This makes the project relevant to teams that want a working starting point and then need to alter the data model or interface. It is less suitable for a buyer who only wants a hosted, hands-off CRM and does not want to manage deployment, database services, or code updates.

React frontend, Supabase services, and CRM data flow

The repository identifies a TypeScript application with a Vite frontend and a Supabase-backed local environment. The package scripts include Vite development and build commands, while the top-level entries include `src/`, `supabase/`, `demo/`, and `e2e/`. Based on that layout, the frontend contains the CRM interface and application logic, while the `supabase/` directory supplies the local API, database, and supporting services described by the installation instructions.

The documented local startup path makes the data flow concrete. `make start` starts the Vite development server, a local Supabase instance for the API, and a Postgres database through Docker. The frontend is then available at `http://localhost:5173/`. Supabase services are exposed separately for administration and debugging: a dashboard, a REST API, an attachments storage location, and an Inbucket email testing service. That separation matters for development because a developer can inspect the backend and test email-related behavior without relying only on the CRM interface.

The feature descriptions also indicate several integration paths. Email can be captured by copying the CRM address, with communications saved as notes. Contacts can be imported and exported. The API is intended to connect the CRM to other systems. The repository includes package dependencies associated with the broader React administration stack, including React administration, query, routing, form, and drag-and-drop libraries, although the truncated package listing does not provide a complete architecture diagram. The supported user-facing mechanisms are nevertheless clear: browser UI, REST API, Supabase services, attachments, and email capture.

Local installation with Make, Node 24 LTS, and Docker

The README gives a direct local setup path. It requires Make, Node 24 LTS, and Docker, with Docker required by Supabase. Because Atomic CRM is intended to be forked before local use, the repository URL in the clone example contains the placeholder `[username]`. Replace that value with the account or organization that owns the fork, then install dependencies with the Make target. The following commands are copied from the documented workflow.

git clone https://github.com/[username]/atomic-crm.git
cd atomic-crm
make install

The install command is documented as installing frontend and backend dependencies, including a local Supabase instance. After configuration is complete, start the full local stack:

make start

The application should then be reachable at the documented frontend address:

http://localhost:5173/

The README says the first user is created through a prompt in the application. It also lists the local Supabase dashboard at `http://localhost:54323/`, the REST API at `http://127.0.0.1:54321`, attachments storage at `http://localhost:54323/project/default/storage/buckets/attachments`, and Inbucket at `http://localhost:54324/`. Those addresses are useful during initial setup because they identify the separate services that the CRM depends on. The documentation says `make install` is required before `make start`, and it does not provide a separate production deployment guide in the README excerpt.

Updating forked CRM components through the shadcn registry

Atomic CRM publishes its components through a shadcn registry. This is a different distribution model from installing the whole application. The README explicitly warns that the registry cannot bootstrap a new CRM application. Instead, it is intended to keep components in a fork synchronized with upstream changes.

Before applying updates, the README instructs users to commit their work. That order matters because the command overwrites files that changed upstream:

npx shadcn add https://marmelab.com/atomic-crm/r/atomic-crm.json -o -y

The `-o` option overwrites changed files, and `-y` skips the confirmation prompt. The documentation recommends this command instead of piping `yes` into the process. A team that has changed registry-managed components should therefore expect to inspect the resulting diff and resolve conflicts. The registry does not describe a migration system for every application-level change, so its update scope should not be treated as equivalent to upgrading the complete CRM.

The repository also documents how the registry is maintained. `scripts/generate-registry.mjs` generates `registry.json` through `make registry-gen`, while CI/CD builds and publishes the remote registry through `make registry-build` and `make registry-deploy`. The README warns that changes missing from `registry.json` require updating the generator script. This is a concrete maintenance constraint for contributors who add components, because the visible source change and the published registry entry must stay aligned.

Testing, customization, and upgrade boundaries

The repository separates unit testing from end-to-end testing. The README documents `make test` for unit tests and `make test-e2e` for end-to-end tests. The package scripts provide narrower commands for application, Claude, and functions projects, including `test:unit:app`, `test:unit:claude`, and `test:unit:functions`. The documented file conventions are also specific: unit test files belong in `src` and use `*.test.tsx` or `*.test.ts`, while end-to-end tests belong in `./e2e`.

The usual end-to-end development command runs the tests in UI mode against a Vite server with hot reload. The README distinguishes this from CI, where end-to-end tests run against the built application. For the built-file workflow, it documents this sequence:

make start-e2e-ci
npx playwright test --ui

Atomic CRM supports customization at several layers. Teams can add custom fields, replace components, and change the theme. The registry provides a channel for component updates, but the overwrite behavior creates a tradeoff: synchronization is easier when customizations are isolated, and conflict review is required when upstream files overlap local work. The README does not document database migrations, rollback procedures, or a production deployment checklist. Those omissions matter for an adopter who intends to operate the CRM beyond local development. The documented tests can check application behavior, but they do not by themselves establish a safe upgrade path for a customized deployment.

Atomic CRM versus a registry-only integration path

The most concrete alternative described in the repository is using the Atomic CRM shadcn registry as an integration path instead of adopting the complete CRM. The registry supplies published components through `atomic-crm.json`, and teams can add or refresh those components with `npx shadcn`. This suits a team that already has an application and wants selected Atomic CRM components or upstream fixes.

The full application follows a different path. It requires a fork, dependency installation, a local Supabase environment, and a database started through Docker. It provides the CRM workflows described in the README, including contacts, tasks, notes, deals, activity history, authentication providers, import and export, attachments, and email capture. The registry cannot provide those application services and cannot bootstrap a new CRM, as the README states directly.

The choice therefore depends on the desired boundary. Use Atomic CRM when the goal is to run and extend a CRM. Use the registry path when the goal is to reuse or synchronize components inside another application. Neither path removes the need to inspect code and configuration, but the registry path does not substitute for deploying the CRM's frontend, Supabase API, Postgres database, storage, and supporting services.

Editorial conclusion

Adopt Atomic CRM when the team needs a forkable CRM with source access, Supabase services, and custom workflows. Do not choose it as a hands-off hosted CRM or ignore the operational work. Verify `make install`, `make start`, the supported authentication providers, and the `npx shadcn add` update behavior before committing to a customized deployment.

Frequently asked questions

Official sources

1. License: MIT
2. marmelab/atomic-crm on GitHub
3. Project website
4. README
5. Releases