Atomic CRM Documentation

The Admin Components provide a suite of building blocks for single-page applications (SPAs). They are built on top of a modern stack including TanStack Query, React Hook Form, React Router, ra-core, Radix UI, and Shadcn UI.

Key features provided by these components include:

• Data Management: Data fetching, lists, data tables, rapid CRUD generation, and relationship management.
• User Interface: Forms & validation, search & filtering, theming, i18n, loading/error management, and notifications.
• Advanced UX: Optimistic UI, undo functionality, bulk actions, and user preferences.
• Security: Authentication, roles, and permissions.

The CRM Builder is a containerized, browser-based alternative to running the harness locally. It is ideal if you want to avoid local setup or security concerns.

Key features include:

• Containerized Environment: Run the harness without affecting your local machine.
• Pre-installed Toolchain: No need to manually install Claude Code, Node, or Supabase.
• Live Preview: See the CRM update in real-time as the harness applies changes.
• Session Dashboard: Visual tracking of agent progress and activity.
• Mode Switching: Easily toggle between Demo and Full-stack modes via the UI.

Atomic CRM supports two interchangeable data providers:

• Supabase: The production-ready provider for persistent storage.
• FakeRest: An in-browser demo provider. Note that data in FakeRest is ephemeral and resets on every page reload.

Atomic CRM is built around several core business resources. When building custom views or integrations, expect to interact with:

• contacts
• companies
• deals (managed via a Kanban pipeline)
• tasks
• notes
• tags
• sales (representing team members)

To reduce HTTP overhead and simplify frontend logic, Atomic CRM uses PostgreSQL database views to aggregate data from multiple tables.

For example, the contact list page uses the contacts_summary view to display the number of tasks associated with each contact. This view is defined in supabase/migrations/init_db.sql.

Note: If you are using the FakeRest data provider, these database views are emulated in the frontend layer.

A Starlight project follows a specific directory structure for content and assets:

• src/content/docs/: Place your .md or .mdx files here. Starlight automatically generates routes based on the filenames.
• src/assets/: Store images here to embed them in Markdown using relative links.
• public/: Place static assets like favicons here.
• astro.config.mjs: The main configuration file for the Astro project.
• package.json: Defines dependencies and scripts.

.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   └── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

Because Supabase's auth.users table cannot be modified with custom columns, Atomic CRM stores additional user details in a separate sales table.

A database trigger is used to automatically synchronize records between these tables (e.g., syncing first_name and last_name fields) whenever a user is created or updated. The trigger implementation is located in supabase/migrations/20240730075425_init_triggers.sql.

Atomic CRM is built using a decoupled architecture consisting of a React-based Single-Page Application (SPA) for the frontend and Supabase for the backend.

Frontend Stack:

• Routing: React Router
• Data Fetching & Caching: React Query
• Form Management: React Hook Form
• UI Components: Shadcn UI and Radix UI
• Styling: Tailwind CSS
• Framework Glue: Shadcn Admin Kit

Backend Stack (Supabase):

• Database: PostgreSQL
• API: REST API
• Authentication & Storage: Supabase built-in services
• Logic: Supabase Edge Functions (used for user management and inbound email processing)

Atomic CRM uses two types of API keys from your Supabase project:

1. Publishable API key: Use this for frontend or client-side code. It has limited permissions and respects Row Level Security (RLS) policies.
2. Secret API key: Use this only on the server side. It provides full database access and should never be exposed to the client.

All requests must include the apikey header. For protected data, you must also include the Authorization: Bearer <jwt_token> header.

The mobile app supports offline mode, allowing you to work without an active internet connection.

Limitations of Offline Mode:

• You can only access data that was previously loaded while the device was online.
• Supported offline data includes your contacts, tasks, and notes.