How hexdevop/crm works
1. System shape
Universal CRM is split into three runnable applications: a FastAPI backend, a React/TypeScript frontend, and a Telegram bot. PostgreSQL is the primary datastore, Redis supports permission caching and pub/sub notifications, and Docker Compose wires the whole stack together for dev and prod.
2. Backend as the core application
The backend under backend/app is the central business layer. main.py boots FastAPI, api/router.py mounts versioned routes, and core/ holds cross-cutting concerns like security, dependency injection, exceptions, and pagination. All domain operations flow through this API layer.
3. Layered backend boundaries
The backend follows a clear separation: API routers call service classes, services orchestrate business rules, repositories perform tenant-scoped database access, and SQLAlchemy models define persistence. Pydantic schemas sit on the edge for request/response validation. This makes the repository the best place to draw a clean diagram with distinct API, service, data-access, and model layers.
4. Multitenancy boundary
The key architectural constraint is row-level tenant isolation. Nearly every user-owned table includes company_id, and repositories require it in queries so records are always filtered by tenant. The README states that authentication middleware extracts company_id from the JWT and attaches it to the request, so tenant context is established once and then propagated downward through dependencies into repositories.
5. Authentication and session flow
The auth subsystem uses a two-token JWT pattern: a short-lived access token returned in the login response and a long-lived refresh token stored in an HttpOnly cookie. Backend auth endpoints live in backend/app/api/v1/auth.py, with supporting logic in services/auth.py, core/security.py, and schemas/auth.py. The frontend keeps the access token in memory/Zustand, while refresh happens transparently via cookie-backed requests.
6. RBAC and permission caching
Roles and permissions are modeled as first-class backend entities (models/role.py, repositories/role.py, services/role.py) and exposed through dedicated API routes. Permission checks are cached in Redis per user and invalidated when role assignments change. Superadmin access is an explicit bypass path that spans all companies.
7. CRM domain modules
The main business domains are company management, users, roles, entities, entity records, movements, access expiration, uploads, and Telegram integration. Each domain has its own trio of router/service/repository files, which suggests the architecture is resource-oriented and domain-separated rather than monolithic. entities and entity_records are especially important because they implement the configurable CRM object model.
8. Dynamic entity model
The entity builder is a core differentiator: entity definitions are stored relationally, while the actual record payload is stored as JSONB. This means schema changes happen at the application layer rather than through frequent migrations. In diagram terms, entities define structure, entity_records store data, and the JSONB field acts as the flexible data boundary.
9. Background jobs and access expiry
backend/app/tasks/ contains scheduler and checker jobs for access expiration. These background tasks periodically evaluate user/company access windows and update account state when access ends. That makes the system partly event/time-driven, not just request-driven.
10. Telegram notification pipeline
Telegram integration is split between backend and a separate bot/ service. The backend publishes notification events to Redis pub/sub; the bot subscribes and sends messages via aiogram 3 to Telegram users. A /connect TOKEN flow links Telegram accounts back to CRM users, so Redis is the bridge between application events and outbound messaging.
11. Frontend structure
The frontend is a Vite-built React SPA in frontend/src. api/ contains Axios clients for each backend resource, hooks/ wraps those calls into reusable data hooks, store/ holds app state like auth/theme/ui, and pages/ is organized by domain: auth, dashboard, entities, records, roles, users, access, admin, and settings. The frontend is therefore a thin client over the backend API, not a separate business-logic system.
12. Navigation, protection, and UI composition
router/ProtectedRoute.tsx and the layouts/ directory show that access control is enforced in the client UI as well, primarily for navigation and UX. Shared UI components under components/ui and layout components like Sidebar and Topbar indicate a shell-based application UI around domain pages.
13. Infrastructure and deployment
Deployment is container-first. docker-compose.dev.yml brings up PostgreSQL, Redis, backend, frontend, and bot with hot reload; docker-compose.prod.yml is the production composition. Backend startup runs Alembic migrations via entrypoint.sh, and production uses nginx to serve the frontend and proxy API traffic, with SSL handled at the edge.
14. Data ownership and external dependencies
PostgreSQL is the system of record for all CRM data, Alembic manages schema evolution, and Redis is a supporting dependency rather than a source of truth. External service interaction is limited mainly to Telegram’s Bot API and the browser client. That keeps the architecture centered on the backend database, with Redis and Telegram as auxiliary integration layers.
Main entry points: App.tsx SPA shell · main.py API app · router.py Route mount · auth.py Auth API
Components 28
Backend
FastAPI API, business logic, persistence, and background jobs.
- API app · Bootstraps the backend application and middleware stack.
backend/app/main.py - Route mount · Collects and mounts versioned backend routes.
backend/app/api/router.py - Auth API · Login, refresh, and authentication endpoints.
backend/app/api/v1/auth.py - Entity API · Entity definitions and configurable CRM object endpoints.
backend/app/api/v1/entities.py - Record API · Entity record CRUD and payload handling.
backend/app/api/v1/entity_records.py - Auth service · Token issuance, session logic, and authentication rules.
backend/app/services/auth.py - Entity service · Coordinates entity definitions and record operations.
backend/app/services/entity.py - Role service · Manages roles, permissions, and access changes.
backend/app/services/role.py - Entity repo · Tenant-scoped persistence for entity definitions and records.
backend/app/repositories/entity.py - Role repo · Persistence for roles and permission assignments.
backend/app/repositories/role.py - Entity model · Relational definition of configurable CRM entities.
backend/app/models/entity.py - Entity schema · Validation layer for entity requests and responses.
backend/app/schemas/entity.py - Security core · JWT, dependency, and request context helpers.
backend/app/core/security.py - Redis client · Permission cache and notification bus integration.
backend/app/redis_client.py - Expiry jobs · Scheduled checks for access expiration and state updates.
backend/app/tasks/scheduler.py
Frontend
React/TypeScript SPA that consumes the backend API.
- SPA shell · Application root for the client-side UI.
frontend/src/App.tsx - API client · Axios layer for backend resource calls.
frontend/src/api/client.ts - Auth store · Keeps access token and session UI state in memory.
frontend/src/store/auth.store.ts - Protected route · Client-side navigation protection and UX gating.
frontend/src/router/ProtectedRoute.tsx - Builder page · UI for configuring CRM entities and related records.
frontend/src/pages/entities/EntityBuilderPage.tsx
Telegram Bot
Separate aiogram service for outbound notifications and account linking.
- Bot app · Starts the Telegram bot service.
bot/bot/main.py - Notifier · Consumes notification events and dispatches Telegram messages.
bot/bot/notifications/dispatcher.py - Connect flow · Links Telegram accounts back to CRM users.
bot/bot/handlers/connect.py
Infra
Container orchestration and deployment entrypoints.
- Compose stack · Wires backend, frontend, bot, Redis, and PostgreSQL for dev and prod.
docker-compose.dev.yml - Backend start · Runs migrations and launches the backend container.
backend/entrypoint.sh
External Systems
Datastore and third-party services the app depends on.
- PostgreSQL · System of record for CRM data.
- Telegram API · Outbound messaging and account linking destination.
- Redis · Shared cache and event transport.
Connections 30
- Compose stack → API app: starts · Docker Compose launches the backend service.
- Compose stack → SPA shell: serves · Compose includes the frontend runtime.
- Compose stack → Bot app: starts · Compose launches the Telegram bot service.
- API app → Route mount: mounts · The backend app attaches the versioned router set.
- Route mount → Auth API: includes · Auth endpoints are part of the API surface.
- Route mount → Entity API: includes · Entity endpoints are part of the API surface.
- Route mount → Record API: includes · Record endpoints are part of the API surface.
- Auth API → Auth service: uses · Endpoints delegate auth logic to services.
- Entity API → Entity service: uses · Entity endpoints delegate domain operations.
- Record API → Entity service: uses · Record endpoints reuse entity orchestration.
- Entity service → Entity repo: calls · Services persist through repositories.
- Role service → Role repo: calls · Role logic is mediated by role repositories.
- Entity repo → Entity model: maps to · Repositories operate on SQLAlchemy models.
- Entity service → Entity schema: validates · Schema boundary protects API inputs and outputs.
- Auth service → Security core: depends on · Security core provides JWT and dependency helpers.
- Security core → Redis: caches permissions · Permission checks are cached in Redis.
- Expiry jobs → PostgreSQL: updates · Background jobs evaluate and mutate expiry state in the database.
- API app → PostgreSQL: reads/writes · The API uses PostgreSQL through the database layer.
- API app → Redis: pub/sub · Backend publishes notification events to Redis.
- Bot app → Notifier: runs · The bot boots the notification worker.
- Notifier → Redis: subscribes · The bot consumes events from Redis pub/sub.
- Notifier → Telegram API: sends · Outbound messages are delivered through Telegram.
- Connect flow → Telegram API: links · The connect command binds Telegram accounts.
- SPA shell → API client: calls · The SPA uses the shared API client.
- SPA shell → Auth store: stores session · Client auth state is kept in the store.
- SPA shell → Protected route: guards · Protected routes enforce UX-level access control.
- SPA shell → Builder page: renders · Entity builder UI is one of the main domain pages.
- API client → API app: requests · Frontend API calls target the backend service.
- Auth store → Auth API: auth flow · Login and token refresh are driven by auth endpoints.
- Auth API → Security core: issues tokens · Auth endpoints rely on core security helpers.