# marmelab/atomic-crm architecture

> Architecture diagram of the GitHub repository marmelab/atomic-crm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marmelab/atomic-crm
- Repository: https://github.com/marmelab/atomic-crm

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend App"
        direction TB
        MainTSX["src/main.tsx"]:::frontend
        AppTSX["src/App.tsx"]:::frontend
        UIFramework["UI Framework\nsrc/components/ui"]:::frontend
        AdminModule["Admin Module\nsrc/components/admin"]:::frontend
        AtomicModule["Atomic-CRM Module\nsrc/components/atomic-crm"]:::frontend
        SupabaseUI["Supabase UI\nsrc/components/supabase"]:::frontend
        Hooks["Hooks\nsrc/hooks"]:::frontend
        subgraph "CRM Feature Root"
            direction TB
            ConfigCtx["Configuration Context\nConfigurationContext.tsx"]:::frontend
            I18nProv["i18n Provider\ni18nProvider.tsx"]:::frontend
            CRMRoot["CRM Root Component\nCRM.tsx"]:::frontend
            FakeREST["FakeREST Provider\nsrc/components/atomic-crm/providers/fakerest"]:::frontend
            SupabaseProvider["Supabase Provider\nsrc/components/atomic-crm/providers/supabase"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Supabase Backend"
        direction TB
        DB["Postgres DB\nsupabase/migrations"]:::db
        Triggers["Triggers & Policies"]:::service
        Auth["Auth Service"]:::service
        Storage["Storage Buckets"]:::storage
        RESTAPI["REST API"]:::service
        Config["Supabase Config\nsupabase/config.toml"]:::service
        subgraph "Edge Functions"
            direction TB
            EdgePostmark["postmark\nsupabase/functions/postmark"]:::fn
            EdgeUpdatePw["updatePassword\nsupabase/functions/updatePassword/index.ts"]:::fn
            EdgeUsers["users\nsupabase/functions/users/index.ts"]:::fn
            SharedUtils["_shared Utils\nsupabase/functions/_shared"]:::fn
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        OAuth["OAuth Providers\nGoogle/Azure/Keycloak/Auth0"]:::external
        Postmark["Postmark Email Service"]:::external
        Inbucket["Inbucket (Local Email)"]:::external
        Browser["Browser/User"]:::external
    end

    %% Data Flows
    Browser -->|"view & interact"| MainTSX
    Browser -.->|"hot reload"| MainTSX
    MainTSX --> AppTSX
    AppTSX --> UIFramework
    UIFramework --> AdminModule
    UIFramework --> AtomicModule
    UIFramework --> SupabaseUI
    AppTSX --> CRMRoot
    CRMRoot -->|"REST CRUD"| RESTAPI
    CRMRoot -->|"invoke"| EdgePostmark
    CRMRoot -->|"invoke"| EdgeUpdatePw
    CRMRoot -->|"invoke"| EdgeUsers
    CRMRoot -->|"dev mode"| FakeREST

    EdgePostmark -->|"writes"| DB
    EdgeUpdatePw -->|"updates"| DB
    EdgeUsers -->|"user events"| DB
    Triggers -->|"enforce"| DB
    RESTAPI -->|"queries"| DB
    Auth -->|"triggers OAuth"| OAuth
    Storage -->|"signed URLs"| Browser
    Postmark -.->|"webhook"| EdgePostmark
    Inbucket -.->|"testing inbound email"| EdgePostmark

    %% Click Events
    click MainTSX "https://github.com/marmelab/atomic-crm/blob/main/src/main.tsx"
    click AppTSX "https://github.com/marmelab/atomic-crm/blob/main/src/App.tsx"
    click UIFramework "https://github.com/marmelab/atomic-crm/tree/main/src/components/ui"
    click AdminModule "https://github.com/marmelab/atomic-crm/tree/main/src/components/admin"
    click AtomicModule "https://github.com/marmelab/atomic-crm/tree/main/src/components/atomic-crm"
    click SupabaseUI "https://github.com/marmelab/atomic-crm/tree/main/src/components/supabase"
    click Hooks "https://github.com/marmelab/atomic-crm/tree/main/src/hooks"
    click ConfigCtx "https://github.com/marmelab/atomic-crm/blob/main/src/components/atomic-crm/root/ConfigurationContext.tsx"
    click I18nProv "https://github.com/marmelab/atomic-crm/blob/main/src/components/atomic-crm/root/i18nProvider.tsx"
    click CRMRoot "https://github.com/marmelab/atomic-crm/blob/main/src/components/atomic-crm/root/CRM.tsx"
    click FakeREST "https://github.com/marmelab/atomic-crm/tree/main/src/components/atomic-crm/providers/fakerest"
    click SupabaseProvider "https://github.com/marmelab/atomic-crm/tree/main/src/components/atomic-crm/providers/supabase"
    click DB "https://github.com/marmelab/atomic-crm/tree/main/supabase/migrations"
    click EdgePostmark "https://github.com/marmelab/atomic-crm/tree/main/supabase/functions/postmark"
    click EdgeUpdatePw "https://github.com/marmelab/atomic-crm/blob/main/supabase/functions/updatePassword/index.ts"
    click EdgeUsers "https://github.com/marmelab/atomic-crm/blob/main/supabase/functions/users/index.ts"
    click SharedUtils "https://github.com/marmelab/atomic-crm/tree/main/supabase/functions/_shared"
    click Config "https://github.com/marmelab/atomic-crm/blob/main/supabase/config.toml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef db fill:#C8E6C9,stroke:#2e7d32,color:#2e7d32
    classDef storage fill:#A5D6A7,stroke:#2e7d32,color:#2e7d32
    classDef service fill:#FFECB3,stroke:#f57c00,color:#e65100
    classDef fn fill:#FFE0B2,stroke:#ef6c00,color:#e65100
    classDef external fill:#E0E0E0,stroke:#616161,color:#424242
```
