# bliss-tech-solutions/leadflow_crm architecture

> Architecture diagram of the GitHub repository bliss-tech-solutions/leadflow_crm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bliss-tech-solutions/leadflow_crm
- Repository: https://github.com/bliss-tech-solutions/leadflow_crm

## Overview

LeadFlow is a real-estate CRM whose central flow captures Meta lead forms, matches them to configured projects, stores leads, then holds or capacity-assigns them for role-scoped sales work and notifications. Admins and sales staff use the Next.js workspace for leads, follow-ups, projects, documents, team, integrations and audit history. The graph includes documented capabilities whose route implementations were not sampled; those links are dashed where wiring is unverified. Other edges cite the server, service, or UI files that show the relationship.

Main entry points: [`backend/src/server.ts`](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/server.ts) (Express API), [`backend/src/services/leadDelivery.service.ts`](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/services/leadDelivery.service.ts) (Hold and assignment), [`backend/src/services/meta.service.ts`](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/services/meta.service.ts) (Lead ingestion), [`backend/src/routes/leads.ts`](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/leads.ts) (Lead workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["CRM workspace"]
  node_workspace_ui["CRM workspace"]
  node_topbar["Notifications UI<br/>[Topbar.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_session["Session storage<br/>[auth.ts]"]
  node_socket_client["Realtime client<br/>[socket.ts]"]
end

subgraph group_api["API and access"]
  node_server["Express API<br/>[server.ts]"]
  node_auth_routes["Authentication<br/>[auth.ts]"]
  node_auth_middleware["JWT and RBAC<br/>[auth.ts]"]
end

subgraph group_leadops["Lead operations"]
  node_meta_routes["Meta webhook routes<br/>[meta.ts]"]
  node_meta_service["Lead ingestion<br/>[meta.service.ts]"]
  node_delivery["Hold and assignment"]
  node_lead_routes["Lead workspace<br/>[leads.ts]"]
  node_followups["Follow-ups<br/>[followups.ts]"]
  node_notifications["Notifications<br/>[notifications.ts]"]
  node_sockets["Socket delivery<br/>[index.ts]"]
end

subgraph group_projectdocs["Projects and documents"]
  node_projects["Business projects"]
  node_documents["Project documents<br/>[documents.ts]"]
  node_s3_service["S3 signing<br/>[s3.service.ts]"]
end

subgraph group_state["Persistence and records"]
  node_team["Users and capacity<br/>[users.ts]"]
  node_audit_routes["Audit history<br/>[audit.ts]"]
  node_activity["Activity and audit log<br/>[activity.ts]"]
  node_lead_store[("Lead records<br/>[Lead.ts]")]
  node_user_store[("User records<br/>[User.ts]")]
  node_project_store[("Project records<br/>[BusinessProject.ts]")]
  node_schedule_store[("Delivery schedule")]
  node_notification_store[("Notification records<br/>[Notification.ts]")]
  node_activity_store[("Activity records<br/>[Activity.ts]")]
  node_audit_store[("Audit records<br/>[Audit.ts]")]
  node_calls_store[("Call records<br/>[Call.ts]")]
  node_followup_store[("Follow-up records<br/>[FollowUp.ts]")]
end

node_admin(("Admin / manager"))
node_sales(("Salesperson"))
node_meta(("Meta Lead Ads"))
node_s3[("AWS S3")]

node_admin -->|"uses"| node_workspace_ui
node_sales -->|"uses"| node_workspace_ui
node_workspace_ui -.->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_server
node_workspace_ui -.->|"uses session"| node_session
node_workspace_ui -.->|"renders"| node_topbar
node_topbar -->|"loads notifications"| node_api_client
node_topbar -->|"listens for events"| node_socket_client
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_meta_routes
node_server -->|"mounts"| node_lead_routes
node_server -->|"mounts"| node_followups
node_server -->|"mounts"| node_projects
node_server -->|"mounts"| node_documents
node_server -->|"mounts"| node_notifications
node_server -->|"mounts"| node_audit_routes
node_server -->|"mounts"| node_team
node_server -->|"sets up"| node_sockets
node_server -->|"schedules release"| node_delivery
node_auth_routes -->|"checks credentials"| node_user_store
node_auth_routes -->|"protects identity route"| node_auth_middleware
node_meta -.->|"sends lead webhook"| node_meta_routes
node_meta_routes -->|"delegates ingestion"| node_meta_service
node_meta_service -->|"fetches lead details"| node_meta
node_meta_service -->|"matches source"| node_project_store
node_meta_service -->|"creates lead"| node_lead_store
node_meta_service -->|"checks hold and capacity"| node_delivery
node_delivery -->|"reads schedule"| node_schedule_store
node_delivery -->|"releases held leads"| node_lead_store
node_delivery -->|"selects salesperson"| node_user_store
node_delivery -->|"creates notifications"| node_notification_store
node_delivery -.->|"emits lead event"| node_sockets
node_lead_routes -->|"reads and updates"| node_lead_store
node_lead_routes -->|"logs activity"| node_activity
node_lead_routes -->|"uses call records"| node_calls_store
node_lead_routes -->|"uses follow-up records"| node_followup_store
node_activity -->|"writes activity"| node_activity_store
node_activity -->|"writes audit"| node_audit_store
node_projects -->|"manages projects"| node_project_store
node_projects -->|"requests signed uploads"| node_s3_service
node_documents -.->|"signs document access"| node_s3_service
node_s3_service -->|"signs object URLs"| node_s3
node_team -.->|"manages users"| node_user_store
node_audit_routes -->|"reads audit records"| node_audit_store
node_meta_service -->|"logs lead events"| node_activity
node_delivery -->|"logs release"| node_activity
node_meta_service -->|"creates scoped alerts"| node_notification_store
node_notifications -.->|"serves inbox"| node_notification_store

click node_workspace_ui "https://github.com/bliss-tech-solutions/leadflow_crm/tree/master/frontend/src/app/(dashboard)"
click node_topbar "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/frontend/src/components/Topbar.tsx"
click node_api_client "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/frontend/src/lib/api.ts"
click node_session "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/frontend/src/lib/auth.ts"
click node_socket_client "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/frontend/src/lib/socket.ts"
click node_server "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/server.ts"
click node_auth_routes "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/auth.ts"
click node_auth_middleware "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/middleware/auth.ts"
click node_meta_routes "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/meta.ts"
click node_meta_service "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/services/meta.service.ts"
click node_delivery "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/services/leadDelivery.service.ts"
click node_lead_routes "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/leads.ts"
click node_followups "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/followups.ts"
click node_notifications "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/notifications.ts"
click node_sockets "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/sockets/index.ts"
click node_projects "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/businessProjects.ts"
click node_documents "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/documents.ts"
click node_s3_service "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/services/s3.service.ts"
click node_team "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/users.ts"
click node_audit_routes "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/audit.ts"
click node_activity "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/utils/activity.ts"
click node_lead_store "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/Lead.ts"
click node_user_store "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/User.ts"
click node_project_store "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/BusinessProject.ts"
click node_schedule_store "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/LeadDeliverySchedule.ts"
click node_notification_store "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/Notification.ts"
click node_activity_store "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/Activity.ts"
click node_audit_store "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/Audit.ts"
click node_calls_store "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/Call.ts"
click node_followup_store "https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/FollowUp.ts"

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_workspace_ui,node_topbar,node_api_client,node_session,node_socket_client toneBlue
class node_server,node_auth_routes,node_auth_middleware,node_s3 toneAmber
class node_meta_routes,node_meta_service,node_delivery,node_lead_routes,node_followups,node_notifications,node_sockets toneMint
class node_projects,node_documents,node_s3_service toneRose
class node_team,node_audit_routes,node_activity,node_lead_store,node_user_store,node_project_store,node_schedule_store,node_notification_store,node_activity_store,node_audit_store,node_calls_store,node_followup_store,node_admin,node_sales,node_meta toneIndigo
```

## Components

### CRM workspace

- [CRM workspace](https://github.com/bliss-tech-solutions/leadflow_crm/tree/master/frontend/src/app/(dashboard)): `frontend/src/app/(dashboard)`
- [Notifications UI](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/frontend/src/components/Topbar.tsx): `frontend/src/components/Topbar.tsx`
- [API client](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Session storage](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/frontend/src/lib/auth.ts): `frontend/src/lib/auth.ts`
- [Realtime client](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/frontend/src/lib/socket.ts): `frontend/src/lib/socket.ts`

### API and access

- [Express API](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/server.ts): `backend/src/server.ts`
- [Authentication](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [JWT and RBAC](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/middleware/auth.ts): `backend/src/middleware/auth.ts`

### Lead operations

- [Meta webhook routes](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/meta.ts): `backend/src/routes/meta.ts`
- [Lead ingestion](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/services/meta.service.ts): `backend/src/services/meta.service.ts`
- [Hold and assignment](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/services/leadDelivery.service.ts): `backend/src/services/leadDelivery.service.ts`
- [Lead workspace](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/leads.ts): `backend/src/routes/leads.ts`
- [Follow-ups](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/followups.ts): `backend/src/routes/followups.ts`
- [Notifications](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/notifications.ts): `backend/src/routes/notifications.ts`
- [Socket delivery](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/sockets/index.ts): `backend/src/sockets/index.ts`

### Projects and documents

- [Business projects](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/businessProjects.ts): `backend/src/routes/businessProjects.ts`
- [Project documents](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/documents.ts): `backend/src/routes/documents.ts`
- [S3 signing](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/services/s3.service.ts): `backend/src/services/s3.service.ts`

### Persistence and records

- [Users and capacity](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/users.ts): `backend/src/routes/users.ts`
- [Audit history](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/routes/audit.ts): `backend/src/routes/audit.ts`
- [Activity and audit log](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/utils/activity.ts): `backend/src/utils/activity.ts`
- [Lead records](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/Lead.ts): `backend/src/models/Lead.ts`
- [User records](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/User.ts): `backend/src/models/User.ts`
- [Project records](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/BusinessProject.ts): `backend/src/models/BusinessProject.ts`
- [Delivery schedule](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/LeadDeliverySchedule.ts): `backend/src/models/LeadDeliverySchedule.ts`
- [Notification records](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/Notification.ts): `backend/src/models/Notification.ts`
- [Activity records](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/Activity.ts): `backend/src/models/Activity.ts`
- [Audit records](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/Audit.ts): `backend/src/models/Audit.ts`
- [Call records](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/Call.ts): `backend/src/models/Call.ts`
- [Follow-up records](https://github.com/bliss-tech-solutions/leadflow_crm/blob/master/backend/src/models/FollowUp.ts): `backend/src/models/FollowUp.ts`

### Other components

- **Admin / manager**
- **Salesperson**
- **Meta Lead Ads**
- **AWS S3**

## Connections

- Admin / manager → CRM workspace: uses (evidence: `README.md`)
- Salesperson → CRM workspace: uses (evidence: `README.md`)
- CRM workspace → API client: requests data (evidence: `frontend/src/app/(dashboard)/business/page.tsx`)
- API client → Express API: calls API
- CRM workspace → Session storage: uses session (evidence: `frontend/src/app/(dashboard)/business/page.tsx`)
- CRM workspace → Notifications UI: renders (evidence: `frontend/src/app/(dashboard)/business/page.tsx`)
- Notifications UI → API client: loads notifications (evidence: `frontend/src/components/Topbar.tsx`)
- Notifications UI → Realtime client: listens for events (evidence: `frontend/src/components/Topbar.tsx`)
- Express API → Authentication: mounts (evidence: `backend/src/server.ts`)
- Express API → Meta webhook routes: mounts (evidence: `backend/src/server.ts`)
- Express API → Lead workspace: mounts (evidence: `backend/src/server.ts`)
- Express API → Follow-ups: mounts (evidence: `backend/src/server.ts`)
- Express API → Business projects: mounts (evidence: `backend/src/server.ts`)
- Express API → Project documents: mounts (evidence: `backend/src/server.ts`)
- Express API → Notifications: mounts (evidence: `backend/src/server.ts`)
- Express API → Audit history: mounts (evidence: `backend/src/server.ts`)
- Express API → Users and capacity: mounts (evidence: `backend/src/server.ts`)
- Express API → Socket delivery: sets up (evidence: `backend/src/server.ts`)
- Express API → Hold and assignment: schedules release (evidence: `backend/src/server.ts`)
- Authentication → User records: checks credentials (evidence: `backend/src/routes/auth.ts`)
- Authentication → JWT and RBAC: protects identity route (evidence: `backend/src/routes/auth.ts`)
- Meta Lead Ads → Meta webhook routes: sends lead webhook (evidence: `README.md`)
- Meta webhook routes → Lead ingestion: delegates ingestion (evidence: `backend/src/routes/meta.ts`)
- Lead ingestion → Meta Lead Ads: fetches lead details (evidence: `backend/src/services/meta.service.ts`)
- Lead ingestion → Project records: matches source (evidence: `backend/src/services/meta.service.ts`)
- Lead ingestion → Lead records: creates lead (evidence: `backend/src/services/meta.service.ts`)
- Lead ingestion → Hold and assignment: checks hold and capacity (evidence: `backend/src/services/meta.service.ts`)
- Hold and assignment → Delivery schedule: reads schedule (evidence: `backend/src/services/leadDelivery.service.ts`)
- Hold and assignment → Lead records: releases held leads (evidence: `backend/src/services/leadDelivery.service.ts`)
- Hold and assignment → User records: selects salesperson (evidence: `backend/src/services/leadDelivery.service.ts`)
- Hold and assignment → Notification records: creates notifications (evidence: `backend/src/services/leadDelivery.service.ts`)
- Hold and assignment → Socket delivery: emits lead event
- Lead workspace → Lead records: reads and updates (evidence: `backend/src/routes/leads.ts`)
- Lead workspace → Activity and audit log: logs activity (evidence: `backend/src/routes/leads.ts`)
- Lead workspace → Call records: uses call records (evidence: `backend/src/routes/leads.ts`)
- Lead workspace → Follow-up records: uses follow-up records (evidence: `backend/src/routes/leads.ts`)
- Activity and audit log → Activity records: writes activity (evidence: `backend/src/utils/activity.ts`)
- Activity and audit log → Audit records: writes audit (evidence: `backend/src/utils/activity.ts`)
- Business projects → Project records: manages projects (evidence: `backend/src/routes/businessProjects.ts`)
- Business projects → S3 signing: requests signed uploads (evidence: `backend/src/routes/businessProjects.ts`)
- Project documents → S3 signing: signs document access
- S3 signing → AWS S3: signs object URLs (evidence: `README.md`)
- Users and capacity → User records: manages users
- Audit history → Audit records: reads audit records (evidence: `backend/src/routes/audit.ts`)
- Lead ingestion → Activity and audit log: logs lead events (evidence: `backend/src/services/meta.service.ts`)
- Hold and assignment → Activity and audit log: logs release (evidence: `backend/src/services/leadDelivery.service.ts`)
- Lead ingestion → Notification records: creates scoped alerts (evidence: `backend/src/services/meta.service.ts`)
- Notifications → Notification records: serves inbox
