How micropyramid/django-crm works
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: crm CRM project · common Common platform · celery.py Redis + Celery · leads Leads
Components 19
Backend
Django REST API, feature apps, shared platform services, and async workers
- CRM project · Project settings, routing, ASGI/WSGI, and Celery bootstrap
backend/crm - Common platform · Auth, permissions, audit, notifications, custom fields, middleware, RLS helpers, and shared base code
backend/common - Leads · Lead models, workflows, kanban, interactions, and API endpoints
backend/leads - Contacts · Contact data, imports, serialization, and API endpoints
backend/contacts - Accounts · Account records, custom fields, tasks, and API endpoints
backend/accounts - Opportunities · Deals, kanban, aging, goals, line items, and workflow rules
backend/opportunity - Cases · Ticketing, routing, approvals, SLA, inbound email, analytics, merge, and escalation
backend/cases - Tasks · Task boards, kanban, calendar views, and task automation
backend/tasks - Invoices · Invoices, estimates, PDFs, public portals, reminders, and recurring flows
backend/invoices - Business hours · Business-hour calendars used by service and workflow logic
backend/business_hours - Macros · Reusable action bundles and render logic for support workflows
backend/macros - Orders · Order records and related persistence models
backend/orders
Clients
Web, mobile, and AI agent entrypoints consuming the CRM API
- Web app · Authenticated CRM UI, no-layout public flows, server routes, and API proxy endpoints
frontend/src/routes - Web UI kit · Reusable components, stores, hooks, API helpers, and shared client utilities
frontend/src/lib - Mobile app · Flutter presentation layer, providers, screens, services, and local models
mobile/lib - MCP 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 · Primary database with row-level security enforcing organization isolation
- Redis + Celery · Broker/cache layer for background jobs, notifications, imports, and mail delivery
backend/crm/celery.py - External services · AWS S3 file storage and AWS SES email delivery used by backend workflows
Connections 22
- 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