# kainaat-fida/localagent-crm-draft1 architecture

> Architecture diagram of the GitHub repository kainaat-fida/localagent-crm-draft1, 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/kainaat-fida/localagent-crm-draft1
- Repository: https://github.com/kainaat-fida/localagent-crm-draft1

## Overview

LocalAgent CRM is a web-based sales and support automation platform. A customer submits an inquiry through the dashboard or API; the backend runs it through safety, intake, knowledge retrieval, lead qualification, response drafting, and supervisor routing, with sensitive actions held for human approval. The dashboard also supports lead and conversation management, knowledge ingestion/search, approvals, and reports. The README documents the agent sequence and capabilities; sampled source and the source index support the API, workflow, persistence, and retrieval links shown here. Some API and workflow implementations were not sampled, so their internal links are documented rather than source-verified.

Main entry points: [`frontend/src/services/api.js`](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/services/api.js) (API client), [`backend/app/graph/nodes.py`](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/graph/nodes.py) (Workflow nodes), [`backend/app/main.py`](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/knowledge.py`](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/knowledge.py) (Knowledge endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["CRM Dashboard"]
  node_dashboard["Dashboard and simulator<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_approval_ui["Approval review<br/>[Approvals.jsx]"]
  node_leads_ui["Lead management<br/>[Leads.jsx]"]
  node_conversation_ui["Conversations<br/>[Conversations.jsx]"]
  node_knowledge_ui["Knowledge workspace<br/>[KnowledgeBase.jsx]"]
  node_reports_ui["Reports<br/>[Reports.jsx]"]
end

subgraph group_api["Backend API"]
  node_server["FastAPI application<br/>[main.py]"]
  node_inquiries_api["Inquiry endpoint<br/>[inquiries.py]"]
  node_leads_api["Lead endpoints<br/>[leads.py]"]
  node_conversations_api["Conversation endpoints<br/>[conversations.py]"]
  node_approvals_api["Approval endpoints<br/>[approvals.py]"]
  node_knowledge_api["Knowledge endpoints<br/>[knowledge.py]"]
  node_reports_api["Report endpoints<br/>[reports.py]"]
end

subgraph group_agents["Inquiry Workflow"]
  node_workflow["LangGraph workflow<br/>[workflow.py]"]
  node_graph_nodes["Workflow nodes<br/>[nodes.py]"]
  node_safety["Safety agent<br/>[safety_agent.py]"]
  node_intake["Intake agent<br/>[intake_agent.py]"]
  node_knowledge_agent["Knowledge agent<br/>[knowledge_agent.py]"]
  node_qualification["Qualification agent"]
  node_response["Response agent<br/>[response_agent.py]"]
  node_supervisor["Supervisor agent"]
  node_approval_rules["Approval rules<br/>[approval_rules.py]"]
  node_lead_scoring["Lead scoring policy<br/>[lead_scoring.py]"]
end

subgraph group_knowledge["Knowledge Retrieval"]
  node_document_loader["Document loading<br/>[document_loader.py]"]
  node_chunker["Text chunking<br/>[chunker.py]"]
  node_embeddings["Embedding generation<br/>[embeddings.py]"]
  node_retriever["Semantic retrieval<br/>[retriever.py]"]
  node_qdrant[("Vector index<br/>[qdrant_client.py]")]
end

subgraph group_data["Persistence and Services"]
  node_groq["Groq inference<br/>[groq_client.py]"]
  node_repositories["CRUD repositories<br/>[repositories.py]"]
  node_models["CRM data models<br/>[models.py]"]
  node_database[("SQL database<br/>[database.py]")]
end

node_customer(("Customer or operator"))

node_customer -.->|"submits inquiry"| node_dashboard
node_dashboard -->|"calls"| node_api_client
node_api_client -->|"submits inquiry"| node_inquiries_api
node_api_client -->|"requests leads"| node_leads_api
node_api_client -->|"requests messages"| node_conversations_api
node_api_client -->|"requests decisions"| node_approvals_api
node_api_client -->|"manages knowledge"| node_knowledge_api
node_api_client -->|"requests summary"| node_reports_api
node_approval_ui -->|"uses"| node_api_client
node_leads_ui -->|"uses"| node_api_client
node_conversation_ui -->|"uses"| node_api_client
node_knowledge_ui -->|"uses"| node_api_client
node_reports_ui -->|"uses"| node_api_client
node_server -->|"registers route"| node_inquiries_api
node_server -->|"registers route"| node_leads_api
node_server -->|"registers route"| node_conversations_api
node_server -->|"registers route"| node_approvals_api
node_server -->|"registers route"| node_knowledge_api
node_server -->|"registers route"| node_reports_api
node_inquiries_api -.->|"runs workflow"| node_workflow
node_workflow -.->|"dispatches nodes"| node_graph_nodes
node_graph_nodes -->|"executes"| node_safety
node_graph_nodes -->|"executes"| node_intake
node_graph_nodes -->|"executes"| node_knowledge_agent
node_graph_nodes -->|"executes"| node_qualification
node_graph_nodes -->|"executes"| node_response
node_graph_nodes -->|"executes"| node_supervisor
node_safety -->|"passes safe inquiry"| node_intake
node_intake -->|"passes context"| node_knowledge_agent
node_knowledge_agent -->|"passes findings"| node_qualification
node_qualification -->|"passes lead context"| node_response
node_response -->|"passes draft"| node_supervisor
node_safety -->|"checks actions"| node_approval_rules
node_response -->|"checks draft"| node_approval_rules
node_qualification -->|"scores lead"| node_lead_scoring
node_knowledge_agent -->|"retrieves context"| node_retriever
node_retriever -->|"embeds query"| node_embeddings
node_retriever -->|"searches vectors"| node_qdrant
node_knowledge_api -->|"loads uploads"| node_document_loader
node_knowledge_api -->|"chunks documents"| node_chunker
node_knowledge_api -->|"embeds chunks"| node_embeddings
node_knowledge_api -->|"indexes chunks"| node_qdrant
node_intake -->|"requests inference"| node_groq
node_response -->|"requests inference"| node_groq
node_graph_nodes -->|"persists workflow"| node_repositories
node_repositories -->|"queries entities"| node_models
node_conversations_api -.->|"uses persistence"| node_repositories
node_approvals_api -.->|"uses persistence"| node_repositories

click node_dashboard "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/services/api.js"
click node_approval_ui "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/pages/Approvals.jsx"
click node_leads_ui "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/pages/Leads.jsx"
click node_conversation_ui "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/pages/Conversations.jsx"
click node_knowledge_ui "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/pages/KnowledgeBase.jsx"
click node_reports_ui "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/pages/Reports.jsx"
click node_server "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/main.py"
click node_inquiries_api "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/inquiries.py"
click node_leads_api "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/leads.py"
click node_conversations_api "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/conversations.py"
click node_approvals_api "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/approvals.py"
click node_knowledge_api "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/knowledge.py"
click node_reports_api "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/reports.py"
click node_workflow "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/graph/workflow.py"
click node_graph_nodes "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/graph/nodes.py"
click node_safety "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/safety_agent.py"
click node_intake "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/intake_agent.py"
click node_knowledge_agent "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/knowledge_agent.py"
click node_qualification "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/qualification_agent.py"
click node_response "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/response_agent.py"
click node_supervisor "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/supervisor_agent.py"
click node_approval_rules "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/policies/approval_rules.py"
click node_lead_scoring "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/policies/lead_scoring.py"
click node_document_loader "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/rag/document_loader.py"
click node_chunker "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/rag/chunker.py"
click node_embeddings "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/rag/embeddings.py"
click node_retriever "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/rag/retriever.py"
click node_qdrant "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/rag/qdrant_client.py"
click node_groq "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/core/groq_client.py"
click node_repositories "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/db/repositories.py"
click node_models "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/db/models.py"
click node_database "https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/db/database.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_dashboard,node_api_client,node_approval_ui,node_leads_ui,node_conversation_ui,node_knowledge_ui,node_reports_ui toneBlue
class node_server,node_inquiries_api,node_leads_api,node_conversations_api,node_approvals_api,node_knowledge_api,node_reports_api toneAmber
class node_workflow,node_graph_nodes,node_safety,node_intake,node_knowledge_agent,node_qualification,node_response,node_supervisor,node_approval_rules,node_lead_scoring toneMint
class node_document_loader,node_chunker,node_embeddings,node_retriever,node_qdrant toneRose
class node_groq,node_repositories,node_models,node_database,node_customer toneIndigo
```

## Components

### CRM Dashboard

- [Dashboard and simulator](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Approval review](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/pages/Approvals.jsx): `frontend/src/pages/Approvals.jsx`
- [Lead management](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/pages/Leads.jsx): `frontend/src/pages/Leads.jsx`
- [Conversations](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/pages/Conversations.jsx): `frontend/src/pages/Conversations.jsx`
- [Knowledge workspace](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/pages/KnowledgeBase.jsx): `frontend/src/pages/KnowledgeBase.jsx`
- [Reports](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/frontend/src/pages/Reports.jsx): `frontend/src/pages/Reports.jsx`

### Backend API

- [FastAPI application](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/main.py): `backend/app/main.py`
- [Inquiry endpoint](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/inquiries.py): `backend/app/api/inquiries.py`
- [Lead endpoints](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/leads.py): `backend/app/api/leads.py`
- [Conversation endpoints](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/conversations.py): `backend/app/api/conversations.py`
- [Approval endpoints](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/approvals.py): `backend/app/api/approvals.py`
- [Knowledge endpoints](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/knowledge.py): `backend/app/api/knowledge.py`
- [Report endpoints](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/api/reports.py): `backend/app/api/reports.py`

### Inquiry Workflow

- [LangGraph workflow](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/graph/workflow.py): `backend/app/graph/workflow.py`
- [Workflow nodes](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/graph/nodes.py): `backend/app/graph/nodes.py`
- [Safety agent](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/safety_agent.py): `backend/app/agents/safety_agent.py`
- [Intake agent](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/intake_agent.py): `backend/app/agents/intake_agent.py`
- [Knowledge agent](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/knowledge_agent.py): `backend/app/agents/knowledge_agent.py`
- [Qualification agent](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/qualification_agent.py): `backend/app/agents/qualification_agent.py`
- [Response agent](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/response_agent.py): `backend/app/agents/response_agent.py`
- [Supervisor agent](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/agents/supervisor_agent.py): `backend/app/agents/supervisor_agent.py`
- [Approval rules](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/policies/approval_rules.py): `backend/app/policies/approval_rules.py`
- [Lead scoring policy](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/policies/lead_scoring.py): `backend/app/policies/lead_scoring.py`

### Knowledge Retrieval

- [Document loading](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/rag/document_loader.py): `backend/app/rag/document_loader.py`
- [Text chunking](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/rag/chunker.py): `backend/app/rag/chunker.py`
- [Embedding generation](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/rag/embeddings.py): `backend/app/rag/embeddings.py`
- [Semantic retrieval](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`
- [Vector index](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/rag/qdrant_client.py): `backend/app/rag/qdrant_client.py`

### Persistence and Services

- [Groq inference](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/core/groq_client.py): `backend/app/core/groq_client.py`
- [CRUD repositories](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/db/repositories.py): `backend/app/db/repositories.py`
- [CRM data models](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [SQL database](https://github.com/kainaat-fida/localagent-crm-draft1/blob/main/backend/app/db/database.py): `backend/app/db/database.py`

### Other components

- **Customer or operator**

## Connections

- Customer or operator → Dashboard and simulator: submits inquiry (evidence: `README.md`)
- Dashboard and simulator → API client: calls (evidence: `frontend/src/App.jsx`)
- API client → Inquiry endpoint: submits inquiry (evidence: `frontend/src/services/api.js`)
- API client → Lead endpoints: requests leads (evidence: `frontend/src/services/api.js`)
- API client → Conversation endpoints: requests messages (evidence: `frontend/src/services/api.js`)
- API client → Approval endpoints: requests decisions (evidence: `frontend/src/services/api.js`)
- API client → Knowledge endpoints: manages knowledge (evidence: `frontend/src/services/api.js`)
- API client → Report endpoints: requests summary (evidence: `frontend/src/services/api.js`)
- Approval review → API client: uses (evidence: `frontend/src/pages/Approvals.jsx`)
- Lead management → API client: uses (evidence: `frontend/src/pages/Leads.jsx`)
- Conversations → API client: uses (evidence: `frontend/src/pages/Conversations.jsx`)
- Knowledge workspace → API client: uses (evidence: `frontend/src/pages/KnowledgeBase.jsx`)
- Reports → API client: uses (evidence: `frontend/src/pages/Reports.jsx`)
- FastAPI application → Inquiry endpoint: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Lead endpoints: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Conversation endpoints: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Approval endpoints: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Knowledge endpoints: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Report endpoints: registers route (evidence: `backend/app/main.py`)
- Inquiry endpoint → LangGraph workflow: runs workflow
- LangGraph workflow → Workflow nodes: dispatches nodes
- Workflow nodes → Safety agent: executes (evidence: `backend/app/graph/nodes.py`)
- Workflow nodes → Intake agent: executes (evidence: `backend/app/graph/nodes.py`)
- Workflow nodes → Knowledge agent: executes (evidence: `backend/app/graph/nodes.py`)
- Workflow nodes → Qualification agent: executes (evidence: `backend/app/graph/nodes.py`)
- Workflow nodes → Response agent: executes (evidence: `backend/app/graph/nodes.py`)
- Workflow nodes → Supervisor agent: executes (evidence: `backend/app/graph/nodes.py`)
- Safety agent → Intake agent: passes safe inquiry (evidence: `README.md`)
- Intake agent → Knowledge agent: passes context (evidence: `README.md`)
- Knowledge agent → Qualification agent: passes findings (evidence: `README.md`)
- Qualification agent → Response agent: passes lead context (evidence: `README.md`)
- Response agent → Supervisor agent: passes draft (evidence: `README.md`)
- Safety agent → Approval rules: checks actions (evidence: `backend/app/agents/safety_agent.py`)
- Response agent → Approval rules: checks draft (evidence: `backend/app/agents/response_agent.py`)
- Qualification agent → Lead scoring policy: scores lead (evidence: `backend/app/agents/qualification_agent.py`)
- Knowledge agent → Semantic retrieval: retrieves context (evidence: `backend/app/agents/knowledge_agent.py`)
- Semantic retrieval → Embedding generation: embeds query (evidence: `backend/app/rag/retriever.py`)
- Semantic retrieval → Vector index: searches vectors (evidence: `backend/app/rag/retriever.py`)
- Knowledge endpoints → Document loading: loads uploads (evidence: `backend/app/api/knowledge.py`)
- Knowledge endpoints → Text chunking: chunks documents (evidence: `backend/app/api/knowledge.py`)
- Knowledge endpoints → Embedding generation: embeds chunks (evidence: `backend/app/api/knowledge.py`)
- Knowledge endpoints → Vector index: indexes chunks (evidence: `backend/app/api/knowledge.py`)
- Intake agent → Groq inference: requests inference (evidence: `backend/app/agents/intake_agent.py`)
- Response agent → Groq inference: requests inference (evidence: `backend/app/agents/response_agent.py`)
- Workflow nodes → CRUD repositories: persists workflow (evidence: `backend/app/graph/nodes.py`)
- CRUD repositories → CRM data models: queries entities (evidence: `backend/app/db/repositories.py`)
- Conversation endpoints → CRUD repositories: uses persistence (evidence: `backend/app/api/conversations.py`)
- Approval endpoints → CRUD repositories: uses persistence (evidence: `backend/app/api/approvals.py`)
