# micropyramid/django-crm architecture

> Architecture diagram of the GitHub repository micropyramid/django-crm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/micropyramid/django-crm
- Repository: https://github.com/micropyramid/django-crm

## Overview

1. **Repository shape**
   - This is a monorepo for a CRM platform with four deliverables: a Django REST backend, a SvelteKit web frontend, a Flutter mobile app, and an MCP server for AI agents.
   - The backend is the system of record; the other clients are thin consumers over its APIs.

2. **Core backend boundary**
   - `backend/` is a Django 5 + Django REST Framework project (`crm/`), split into feature apps rather than a single domain layer.
   - Major business modules are `leads`, `contacts`, `accounts`, `opportunity`, `cases`, `tasks`, `invoices`, `business_hours`, `macros`, and `orders`.
   - Each module owns its own models, serializers, views, URLs, tests, and migrations.

3. **Shared platform layer**
   - `backend/common/` contains cross-cutting infrastructure used by all apps: auth, permissions, audit log, notifications, custom fields, duplicate detection, middleware, RLS helpers, and shared serializers/base classes.
   - This is the main boundary for platform concerns that should not live inside a single CRM domain module.
   - It also includes management commands for seeding, admin creation, RLS management, and dev login.

4. **Multi-tenancy and data isolation**
   - The repository’s defining architectural choice is PostgreSQL Row-Level Security.
   - Tenant context is injected through middleware in `backend/common/middleware/` and RLS helpers in `backend/common/rls/`.
   - Most domain models are organization-scoped, and migrations explicitly enable RLS on key tables; the backend is designed so database queries are filtered by org context rather than by application-side filtering alone.

5. **Web API flow**
   - All external clients talk to the backend through REST endpoints organized per module.
   - Typical flow is: request enters Django → auth/tenant context is resolved → DRF view/query logic runs → serializer shapes output → response returns JSON.
   - Swagger/OpenAPI support is built in via `schema.yml` and custom OpenAPI helpers in `backend/common/custom_openapi.py`.

6. **Authentication and access**
   - The platform uses JWT-based authentication for end users.
   - It also supports personal access tokens in the API token area, which are reused by the MCP server.
   - The backend contains dedicated auth, permission, and external-auth utilities, indicating multiple login paths and role-based access control layered on top of tenant isolation.

7. **Asynchronous and event-driven work**
   - Celery is a first-class subsystem in the backend, with task modules spread across domain apps and a project-level worker entrypoint in `crm/celery.py`.
   - Redis is the broker/cache layer used to offload email delivery, notifications, import jobs, and other background processing.
   - Signals, notification helpers, and task modules suggest that user actions often trigger secondary asynchronous effects rather than doing everything inline.

8. **Domain workflows**
   - Several modules go beyond CRUD and implement workflow-style behavior: `cases` has routing, approvals, SLA pause, merging, inbound email parsing, analytics, and escalation; `opportunity` has kanban, aging, and sales goals; `tasks` has boards and calendar views; `invoices` has PDFs, reminders, recurring/batch behavior.
   - These workflows are separated into specialized modules and view files, which is a strong hint that the architecture treats these as bounded subdomains with their own rules and state transitions.

9. **Front-end architecture**
   - `frontend/` is a SvelteKit 2 + Svelte 5 application.
   - It uses server routes and page loaders under `src/routes/`, with two main route groups: `(app)` for authenticated screens and `(no-layout)` for login/portal/public flows.
   - `src/lib/` holds reusable UI components, stores, hooks, and API helpers; the route layer is mostly composition and page orchestration.

10. **Web UI to backend relationship**
   - The frontend does not appear to own business data; it fetches and mutates data through the Django API.
   - The route structure mirrors domain modules: tickets, tasks, leads, opportunities, accounts, contacts, invoices, settings, and support flows.
   - Some `frontend/src/routes/api/*` endpoints act as SvelteKit server-side proxies or convenience endpoints for browser interactions such as SSE notifications, approvals, and time entries.

11. **Mobile client**
   - `mobile/` is a Flutter app with its own presentation layer, state providers, and API service layer.
   - It mirrors a subset of the CRM domain: auth, dashboard, leads, deals/opportunities, tasks, tickets, approvals, and settings/profile.
   - Its architecture is client-side MV-ish: services talk to the backend API, providers manage state, screens compose widgets, and the app reuses its own data models rather than sharing backend code.

12. **AI agent integration**
   - `mcp_server/` is a separate Python package implementing a Model Context Protocol server.
   - It wraps the CRM REST API behind MCP tools so AI clients can search and manipulate CRM records using a personal access token.
   - This server sits outside the main app runtime, but it is security-bound to the same user/org/RLS context as the backend.

13. **Infrastructure and external services**
   - PostgreSQL is the primary datastore, with RLS as a core security mechanism.
   - Redis supports caching and Celery queues.
   - AWS S3 is used for file storage, and AWS SES for email delivery.
   - Docker Compose is the main local integration environment, bringing up backend, frontend, Postgres, Redis, and worker processes together.

14. **What to emphasize in an architecture diagram**
   - Show the backend as the central hub with shared auth/RLS/notifications infrastructure and feature apps around it.
   - Draw separate client boundaries for SvelteKit web, Flutter mobile, and MCP server, all consuming the backend API.
   - Include PostgreSQL as the authoritative data store with RLS enforcement, and Redis/Celery as the async processing path.
   - Highlight that tenant isolation is enforced at the database layer, not just in the UI or API.

Main entry points: [`backend/crm`](https://github.com/micropyramid/django-crm/tree/master/backend/crm) (CRM project), [`backend/common`](https://github.com/micropyramid/django-crm/tree/master/backend/common) (Common platform), [`backend/crm/celery.py`](https://github.com/micropyramid/django-crm/blob/master/backend/crm/celery.py) (Redis + Celery), [`backend/leads`](https://github.com/micropyramid/django-crm/tree/master/backend/leads) (Leads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_crm_project["CRM project<br/>Django 5 project"]
  node_backend_common["Common platform<br/>shared infra"]
  node_backend_leads["Leads<br/>CRM feature app"]
  node_backend_contacts["Contacts<br/>CRM feature app"]
  node_backend_accounts["Accounts<br/>CRM feature app"]
  node_backend_opportunity["Opportunities<br/>CRM feature app"]
  node_backend_cases["Cases<br/>support app"]
  node_backend_tasks["Tasks<br/>work app"]
  node_backend_invoices["Invoices<br/>billing app"]
  node_backend_business_hours["Business hours<br/>scheduling app"]
  node_backend_macros["Macros<br/>automation app"]
  node_backend_orders["Orders<br/>sales app"]
end

subgraph group_clients["Clients"]
  node_frontend_web["Web app<br/>SvelteKit client"]
  node_frontend_lib["Web UI kit<br/>Svelte components"]
  node_mobile_app["Mobile app<br/>Flutter client"]
  node_mcp_server["MCP server<br/>Python tools server"]
end

subgraph group_infra["Data & Infra"]
  node_postgresql[("PostgreSQL<br/>authoritative datastore")]
  node_redis_celery["Redis + Celery<br/>async runtime<br/>[celery.py]"]
  node_external_services(("External services<br/>storage/mail"))
end

node_backend_common -->|"RLS context"| node_postgresql
node_crm_project -->|"shared services"| node_backend_common
node_crm_project -->|"routes"| node_backend_leads
node_crm_project -->|"routes"| node_backend_contacts
node_crm_project -->|"routes"| node_backend_accounts
node_crm_project -->|"routes"| node_backend_opportunity
node_crm_project -->|"routes"| node_backend_cases
node_crm_project -->|"routes"| node_backend_tasks
node_crm_project -->|"routes"| node_backend_invoices
node_crm_project -->|"routes"| node_backend_business_hours
node_crm_project -->|"routes"| node_backend_macros
node_crm_project -->|"routes"| node_backend_orders
node_backend_leads -->|"CRUD"| node_postgresql
node_backend_cases -->|"tasks"| node_redis_celery
node_backend_invoices -->|"pdf/email"| node_external_services
node_backend_common -->|"notifications"| node_redis_celery
node_frontend_web -->|"REST API"| node_crm_project
node_frontend_lib -->|"UI layer"| node_frontend_web
node_mobile_app -->|"REST API"| node_crm_project
node_mcp_server -->|"MCP tools"| node_crm_project
node_crm_project -->|"system of record"| node_postgresql
node_crm_project -->|"background work"| node_redis_celery

click node_crm_project "https://github.com/micropyramid/django-crm/tree/master/backend/crm"
click node_backend_common "https://github.com/micropyramid/django-crm/tree/master/backend/common"
click node_backend_leads "https://github.com/micropyramid/django-crm/tree/master/backend/leads"
click node_backend_contacts "https://github.com/micropyramid/django-crm/tree/master/backend/contacts"
click node_backend_accounts "https://github.com/micropyramid/django-crm/tree/master/backend/accounts"
click node_backend_opportunity "https://github.com/micropyramid/django-crm/tree/master/backend/opportunity"
click node_backend_cases "https://github.com/micropyramid/django-crm/tree/master/backend/cases"
click node_backend_tasks "https://github.com/micropyramid/django-crm/tree/master/backend/tasks"
click node_backend_invoices "https://github.com/micropyramid/django-crm/tree/master/backend/invoices"
click node_backend_business_hours "https://github.com/micropyramid/django-crm/tree/master/backend/business_hours"
click node_backend_macros "https://github.com/micropyramid/django-crm/tree/master/backend/macros"
click node_backend_orders "https://github.com/micropyramid/django-crm/tree/master/backend/orders"
click node_frontend_web "https://github.com/micropyramid/django-crm/tree/master/frontend/src/routes"
click node_frontend_lib "https://github.com/micropyramid/django-crm/tree/master/frontend/src/lib"
click node_mobile_app "https://github.com/micropyramid/django-crm/tree/master/mobile/lib"
click node_mcp_server "https://github.com/micropyramid/django-crm/tree/master/mcp_server/src/bcrm_mcp"
click node_redis_celery "https://github.com/micropyramid/django-crm/blob/master/backend/crm/celery.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_crm_project,node_backend_common,node_backend_leads,node_backend_contacts,node_backend_accounts,node_backend_opportunity,node_backend_cases,node_backend_tasks,node_backend_invoices,node_backend_business_hours,node_backend_macros,node_backend_orders toneBlue
class node_frontend_web,node_frontend_lib,node_mobile_app,node_mcp_server toneAmber
class node_postgresql,node_redis_celery,node_external_services toneMint
```

## Components

### Backend

Django REST API, feature apps, shared platform services, and async workers

- [CRM project](https://github.com/micropyramid/django-crm/tree/master/backend/crm): Django 5 project · Project settings, routing, ASGI/WSGI, and Celery bootstrap · `backend/crm`
- [Common platform](https://github.com/micropyramid/django-crm/tree/master/backend/common): shared infra · Auth, permissions, audit, notifications, custom fields, middleware, RLS helpers, and shared base code · `backend/common`
- [Leads](https://github.com/micropyramid/django-crm/tree/master/backend/leads): CRM feature app · Lead models, workflows, kanban, interactions, and API endpoints · `backend/leads`
- [Contacts](https://github.com/micropyramid/django-crm/tree/master/backend/contacts): CRM feature app · Contact data, imports, serialization, and API endpoints · `backend/contacts`
- [Accounts](https://github.com/micropyramid/django-crm/tree/master/backend/accounts): CRM feature app · Account records, custom fields, tasks, and API endpoints · `backend/accounts`
- [Opportunities](https://github.com/micropyramid/django-crm/tree/master/backend/opportunity): CRM feature app · Deals, kanban, aging, goals, line items, and workflow rules · `backend/opportunity`
- [Cases](https://github.com/micropyramid/django-crm/tree/master/backend/cases): support app · Ticketing, routing, approvals, SLA, inbound email, analytics, merge, and escalation · `backend/cases`
- [Tasks](https://github.com/micropyramid/django-crm/tree/master/backend/tasks): work app · Task boards, kanban, calendar views, and task automation · `backend/tasks`
- [Invoices](https://github.com/micropyramid/django-crm/tree/master/backend/invoices): billing app · Invoices, estimates, PDFs, public portals, reminders, and recurring flows · `backend/invoices`
- [Business hours](https://github.com/micropyramid/django-crm/tree/master/backend/business_hours): scheduling app · Business-hour calendars used by service and workflow logic · `backend/business_hours`
- [Macros](https://github.com/micropyramid/django-crm/tree/master/backend/macros): automation app · Reusable action bundles and render logic for support workflows · `backend/macros`
- [Orders](https://github.com/micropyramid/django-crm/tree/master/backend/orders): sales app · Order records and related persistence models · `backend/orders`

### Clients

Web, mobile, and AI agent entrypoints consuming the CRM API

- [Web app](https://github.com/micropyramid/django-crm/tree/master/frontend/src/routes): SvelteKit client · Authenticated CRM UI, no-layout public flows, server routes, and API proxy endpoints · `frontend/src/routes`
- [Web UI kit](https://github.com/micropyramid/django-crm/tree/master/frontend/src/lib): Svelte components · Reusable components, stores, hooks, API helpers, and shared client utilities · `frontend/src/lib`
- [Mobile app](https://github.com/micropyramid/django-crm/tree/master/mobile/lib): Flutter client · Flutter presentation layer, providers, screens, services, and local models · `mobile/lib`
- [MCP server](https://github.com/micropyramid/django-crm/tree/master/mcp_server/src/bcrm_mcp): Python tools server · Model Context Protocol server that wraps CRM REST APIs for AI agents · `mcp_server/src/bcrm_mcp`

### Data & Infra

Database, cache/queue, and external delivery/storage services

- **PostgreSQL**: authoritative datastore · Primary database with row-level security enforcing organization isolation
- [Redis + Celery](https://github.com/micropyramid/django-crm/blob/master/backend/crm/celery.py): async runtime · Broker/cache layer for background jobs, notifications, imports, and mail delivery · `backend/crm/celery.py`
- **External services**: storage/mail · AWS S3 file storage and AWS SES email delivery used by backend workflows

## Connections

- Common platform → PostgreSQL: RLS context · Middleware and helpers inject tenant context and enforce database isolation
- CRM project → Common platform: shared services · Project wiring includes auth, middleware, URLs, and common utilities
- CRM project → Leads: routes · Project URL configuration exposes feature app APIs
- CRM project → Contacts: routes · Project URL configuration exposes feature app APIs
- CRM project → Accounts: routes · Project URL configuration exposes feature app APIs
- CRM project → Opportunities: routes · Project URL configuration exposes feature app APIs
- CRM project → Cases: routes · Project URL configuration exposes feature app APIs
- CRM project → Tasks: routes · Project URL configuration exposes feature app APIs
- CRM project → Invoices: routes · Project URL configuration exposes feature app APIs
- CRM project → Business hours: routes · Project URL configuration exposes feature app APIs
- CRM project → Macros: routes · Project URL configuration exposes feature app APIs
- CRM project → Orders: routes · Project URL configuration exposes feature app APIs
- Leads → PostgreSQL: CRUD · Domain data is persisted in tenant-scoped tables
- Cases → Redis + Celery: tasks · Escalations, imports, notifications, and async workflows run in background workers
- Invoices → External services: pdf/email · Invoice PDFs and outbound mail use external delivery services
- Common platform → Redis + Celery: notifications · Common async jobs and event-driven helpers share the worker path
- Web app → CRM project: REST API · SvelteKit pages and server routes fetch and mutate CRM data through Django
- Web UI kit → Web app: UI layer · Reusable components and helpers support route composition
- Mobile app → CRM project: REST API · Flutter services and providers consume the backend API
- MCP server → CRM project: MCP tools · AI tools proxy CRM actions through the backend using personal access tokens
- CRM project → PostgreSQL: system of record · All domain apps persist authoritative CRM data in PostgreSQL
- CRM project → Redis + Celery: background work · Celery offloads email, notifications, and import jobs from request flow
