How marmelab/atomic-crm works
Project Type and Purpose
• Atomic CRM is a full-stack, open-source CRM (Customer-Relationship-Management) application.
• Frontend: React + Vite + TypeScript + shadcn-admin-kit components.
• Backend: Supabase (Postgres DB + Auth + Storage + Edge Functions + REST API).
File Structure
• src/ & components/: Application UI, custom React components organized by feature (admin, atomic-crm, supabase, ui).
• supabase/: Local Supabase instance configuration
– migrations/: SQL schema and trigger migrations
– functions/: serverless edge-functions (inbound email, auth, user events)
• demo/: a standalone Vite/React demo of the library.
• doc/: developer and user documentation site (Astro).
• scripts/: helper scripts (registry generation, deployment, Supabase init).
• makefile: orchestrates install, start, test.
Extracted Architectural Insights from README
• Integrations: Google, Azure, Keycloak, Auth0 for SSO
• Inbound email capture via Postmark functions
• Fake-REST data-provider for development
• Registry for publishing components
Main Components
A. Frontend Layer (React App)
– Vite Development Server (src/main.tsx, App.tsx)
– UI Framework (shadcn components under src/components/ui)
– Feature Modules (atomic-crm, admin, supabase components)
– Data-Provider Abstraction (fakerest & supabase under src/components/atomic-crm/providers)
– Context & Hooks (configuration, theme, i18n, saved-queries)
B. Backend Layer (Supabase Instance)
– Postgres Database (schemas from migrations/)
– Auth Service (email/password, SSO)
– Storage Buckets (attachments)
– REST API (auto-generated by Supabase at port 54321)
– Edge Functions (inbound-email, postmark integration, updatePassword, users)
– Triggers & Policies (RLS from migrations/)
C. External Systems
– OAuth Providers: Google, Azure, Keycloak, Auth0
– Postmark Email Service (webhook to Supabase function)
– Inbucket (local email testing)
– Browser / User
Relationships and Data Flows
• Browser ↔ Frontend: HTTP/WebSocket (hot reload, user interactions)
• Frontend ↔ Supabase REST API: CRUD calls (contacts, deals, tasks, notes)
• Frontend ↔ Supabase Edge Functions: inbound-email, custom business logic
• Supabase Edge Functions ↔ Postgres: write notes, triggers, policies
• Supabase Auth ↔ OAuth Providers: redirect flows
• Supabase Storage ↔ Browser: file upload/download via signed URLs
• Optional: Frontend ↔ FakeREST Provider (for local dev)
Architectural Patterns & Principles
• Component-based UI with clear separation by feature and domain
• Provider pattern for swapping data backends (fakerest vs. supabase)
• Serverless functions for extending core business logic (email parsing, password resets)
• Infrastructure-as-Code (SQL migrations under supabase/)
• CI/CD pipelines (GitHub Actions for checks, deploy, registry publishing)