# nocobase/nococrm architecture

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

- Interactive diagram: https://gitdiagram.com/nocobase/nococrm
- Repository: https://github.com/nocobase/nococrm

## Overview

NocoCRM is a self-hosted B2B sales CRM built on NocoBase. Sales users work leads, companies, contacts, opportunities, tasks, and approvals through the client; server-side CRM services enforce record permissions and persist changes. Its distinctive workflow is that background agents use record context and business guidance to propose follow-ups or approval recommendations in the inbox, leaving changes for a person to accept. Mail and WhatsApp add conversation channels; capture, company research, reports, and configurable agent skills are separate capabilities. The graph follows README workflows and indexed imports; unsampled route and integration wiring is not asserted.

Main entry points: [`client/pages`](https://github.com/nocobase/nococrm/tree/main/client/pages) (CRM workspace), [`server/providers/crm/service.ts`](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/service.ts) (CRM service), [`server/providers/crm/plans/engine.ts`](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/plans/engine.ts) (Plan engine), [`server/providers/crm-agents/work-agents.ts`](https://github.com/nocobase/nococrm/blob/main/server/providers/crm-agents/work-agents.ts) (Background agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["CRM experience"]
  node_crm_client["CRM workspace"]
  node_client_routes["Client routes<br/>[routes.ts]"]
  node_inbox["Agent inbox<br/>[inbox.tsx]"]
end

subgraph group_domain["Sales domain"]
  node_crm_api["CRM routes<br/>[crm.ts]"]
  node_crm_service["CRM service<br/>[service.ts]"]
  node_crm_schema["CRM schema<br/>[schema.ts]"]
  node_crm_store[("CRM database<br/>[service.ts]")]
  node_capture["Smart capture<br/>[lead-capture.ts]"]
  node_research["Company research<br/>[company-profile.ts]"]
  node_reports["Sales reports<br/>[reports.ts]"]
end

subgraph group_agents["Agent operations"]
  node_agent_assistant["Sales Expert<br/>[assistant.ts]"]
  node_background_agents["Background agents<br/>[work-agents.ts]"]
  node_plan_engine["Plan engine<br/>[engine.ts]"]
  node_guidance["Agent guidance<br/>[guidance.ts]"]
  node_model_services["AI model services<br/>[model-services.ts]"]
end

subgraph group_channels["Communications"]
  node_mail["Email channel<br/>[demo-mail.ts]"]
  node_whatsapp["WhatsApp channel<br/>[service.ts]"]
end

subgraph group_platform["Access and platform"]
  node_authorization["Record authorization<br/>[authorization.ts]"]
end

node_sales_user(("Sales user"))
node_model_provider["AI model provider"]
node_external_mail["Mail providers"]
node_external_whatsapp["WhatsApp Business"]

node_sales_user -->|"opens CRM"| node_client_routes
node_client_routes -->|"routes pages"| node_crm_client
node_sales_user -->|"reviews proposals"| node_inbox
node_crm_client -.->|"uses CRM"| node_crm_api
node_crm_api -.->|"dispatches requests"| node_crm_service
node_crm_service -->|"reads and writes"| node_crm_store
node_crm_service -->|"uses definitions"| node_crm_schema
node_crm_service -->|"checks access"| node_authorization
node_crm_client -.->|"submits material"| node_capture
node_capture -.->|"creates reviewed records"| node_crm_store
node_background_agents -.->|"reads record context"| node_crm_store
node_background_agents -.->|"follows guidance"| node_guidance
node_background_agents -.->|"proposes next steps"| node_plan_engine
node_plan_engine -.->|"stores proposed changes"| node_crm_store
node_plan_engine -.->|"queues proposals"| node_inbox
node_inbox -.->|"accepts decisions"| node_plan_engine
node_agent_assistant -->|"uses models"| node_model_services
node_model_services -.->|"connects optionally"| node_model_provider
node_crm_client -.->|"manages conversations"| node_mail
node_crm_client -.->|"manages conversations"| node_whatsapp
node_mail -.->|"sends and receives"| node_external_mail
node_whatsapp -.->|"exchanges messages"| node_external_whatsapp
node_research -.->|"researches companies"| node_model_provider
node_crm_client -.->|"views reporting"| node_reports

click node_crm_client "https://github.com/nocobase/nococrm/tree/main/client/pages"
click node_client_routes "https://github.com/nocobase/nococrm/blob/main/client/routes.ts"
click node_inbox "https://github.com/nocobase/nococrm/blob/main/client/pages/inbox.tsx"
click node_crm_api "https://github.com/nocobase/nococrm/blob/main/server/routes/crm.ts"
click node_crm_service "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/service.ts"
click node_crm_schema "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/schema.ts"
click node_crm_store "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/service.ts"
click node_capture "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/lead-capture.ts"
click node_research "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/company-profile.ts"
click node_reports "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/reports.ts"
click node_agent_assistant "https://github.com/nocobase/nococrm/blob/main/server/providers/crm-agents/assistant.ts"
click node_background_agents "https://github.com/nocobase/nococrm/blob/main/server/providers/crm-agents/work-agents.ts"
click node_plan_engine "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/plans/engine.ts"
click node_guidance "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/guidance.ts"
click node_model_services "https://github.com/nocobase/nococrm/blob/main/server/providers/crm-agents/model-services.ts"
click node_mail "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/demo-mail.ts"
click node_whatsapp "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/whatsapp/service.ts"
click node_authorization "https://github.com/nocobase/nococrm/blob/main/server/providers/crm/authorization.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_crm_client,node_client_routes,node_inbox,node_sales_user toneBlue
class node_crm_api,node_crm_service,node_crm_schema,node_crm_store,node_capture,node_research,node_reports toneAmber
class node_agent_assistant,node_background_agents,node_plan_engine,node_guidance,node_model_services toneMint
class node_mail,node_whatsapp toneRose
class node_authorization,node_model_provider,node_external_mail,node_external_whatsapp toneIndigo
```

## Components

### CRM experience

- [CRM workspace](https://github.com/nocobase/nococrm/tree/main/client/pages): `client/pages`
- [Client routes](https://github.com/nocobase/nococrm/blob/main/client/routes.ts): `client/routes.ts`
- [Agent inbox](https://github.com/nocobase/nococrm/blob/main/client/pages/inbox.tsx): `client/pages/inbox.tsx`

### Sales domain

- [CRM routes](https://github.com/nocobase/nococrm/blob/main/server/routes/crm.ts): `server/routes/crm.ts`
- [CRM service](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/service.ts): `server/providers/crm/service.ts`
- [CRM schema](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/schema.ts): `server/providers/crm/schema.ts`
- [CRM database](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/service.ts): `server/providers/crm/service.ts`
- [Smart capture](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/lead-capture.ts): `server/providers/crm/lead-capture.ts`
- [Company research](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/company-profile.ts): `server/providers/crm/company-profile.ts`
- [Sales reports](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/reports.ts): `server/providers/crm/reports.ts`

### Agent operations

- [Sales Expert](https://github.com/nocobase/nococrm/blob/main/server/providers/crm-agents/assistant.ts): `server/providers/crm-agents/assistant.ts`
- [Background agents](https://github.com/nocobase/nococrm/blob/main/server/providers/crm-agents/work-agents.ts): `server/providers/crm-agents/work-agents.ts`
- [Plan engine](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/plans/engine.ts): `server/providers/crm/plans/engine.ts`
- [Agent guidance](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/guidance.ts): `server/providers/crm/guidance.ts`
- [AI model services](https://github.com/nocobase/nococrm/blob/main/server/providers/crm-agents/model-services.ts): `server/providers/crm-agents/model-services.ts`

### Communications

- [Email channel](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/demo-mail.ts): `server/providers/crm/demo-mail.ts`
- [WhatsApp channel](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/whatsapp/service.ts): `server/providers/crm/whatsapp/service.ts`

### Access and platform

- [Record authorization](https://github.com/nocobase/nococrm/blob/main/server/providers/crm/authorization.ts): `server/providers/crm/authorization.ts`

### Other components

- **Sales user**
- **AI model provider**
- **Mail providers**
- **WhatsApp Business**

## Connections

- Sales user → Client routes: opens CRM (evidence: `client/routes.ts`)
- Client routes → CRM workspace: routes pages (evidence: `client/routes.ts`)
- Sales user → Agent inbox: reviews proposals
- CRM workspace → CRM routes: uses CRM
- CRM routes → CRM service: dispatches requests
- CRM service → CRM database: reads and writes (evidence: `server/providers/crm/service.ts`)
- CRM service → CRM schema: uses definitions (evidence: `server/providers/crm/service.ts`)
- CRM service → Record authorization: checks access (evidence: `server/providers/crm/service.ts`)
- CRM workspace → Smart capture: submits material
- Smart capture → CRM database: creates reviewed records
- Background agents → CRM database: reads record context
- Background agents → Agent guidance: follows guidance
- Background agents → Plan engine: proposes next steps
- Plan engine → CRM database: stores proposed changes (evidence: `server/providers/crm/plans/engine.ts`)
- Plan engine → Agent inbox: queues proposals
- Agent inbox → Plan engine: accepts decisions
- Sales Expert → AI model services: uses models (evidence: `server/providers/crm-agents/assistant.ts`)
- AI model services → AI model provider: connects optionally
- CRM workspace → Email channel: manages conversations
- CRM workspace → WhatsApp channel: manages conversations
- Email channel → Mail providers: sends and receives
- WhatsApp channel → WhatsApp Business: exchanges messages
- Company research → AI model provider: researches companies
- CRM workspace → Sales reports: views reporting