# lucas-m-fr/ai-crm-agent architecture

> Architecture diagram of the GitHub repository lucas-m-fr/ai-crm-agent, 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/lucas-m-fr/ai-crm-agent
- Repository: https://github.com/lucas-m-fr/ai-crm-agent
- Video tour (about a minute): https://gitdiagram.com/lucas-m-fr/ai-crm-agent/video

## Overview

This is a small outbound sales CRM agent whose workflow moves prospects through contact, reply classification, lifecycle updates, and suppression. The runnable demo in main.py initializes and seeds the database, then exercises outreach, inbox replies, and follow-ups. Outreach checks suppression and prospect state before recording a generated Message-ID and contact status; inbox processing matches replies by header or sender, classifies intent, and updates state. The follow-up worker selects stale prospects and delegates sending to outreach. SMTP delivery is only a placeholder, and the inbox is simulated; those integrations are not shown as live services.

Main entry points: [`main.py`](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/main.py) (Demo runner), [`db/database.py`](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/db/database.py) (CRM database), [`agent/inbox_reader.py`](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/agent/inbox_reader.py) (Inbox reader), [`agent/outreach.py`](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/agent/outreach.py) (Outreach sender)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow orchestration"]
  node_demo["Demo runner<br/>[main.py]"]
  node_followup_worker["Follow-up worker<br/>[follow_up.py]"]
end

subgraph group_outreach["Outbound outreach"]
  node_outreach_sender["Outreach sender<br/>[outreach.py]"]
end

subgraph group_inbox["Reply processing"]
  node_inbox_reader["Inbox reader<br/>[inbox_reader.py]"]
  node_intent_classifier["Intent classifier<br/>[classifier.py]"]
end

subgraph group_lifecycle["Lifecycle and persistence"]
  node_guardrails["Suppression guardrails<br/>[guardrails.py]"]
  node_crm_store[("CRM database<br/>[database.py]")]
end

node_operator(("CLI operator"))

node_operator -->|"runs"| node_demo
node_demo -->|"initializes and seeds"| node_crm_store
node_demo -->|"starts outreach"| node_outreach_sender
node_demo -->|"simulates replies"| node_inbox_reader
node_demo -->|"runs worker"| node_followup_worker
node_outreach_sender -->|"checks suppression"| node_guardrails
node_outreach_sender -->|"reads and updates"| node_crm_store
node_guardrails -->|"reads and writes"| node_crm_store
node_inbox_reader -->|"matches and updates"| node_crm_store
node_inbox_reader -->|"classifies body"| node_intent_classifier
node_inbox_reader -->|"records opt-out"| node_guardrails
node_followup_worker -->|"queries stale prospects"| node_crm_store
node_followup_worker -->|"delegates sending"| node_outreach_sender

click node_demo "https://github.com/lucas-m-fr/ai-crm-agent/blob/main/main.py"
click node_outreach_sender "https://github.com/lucas-m-fr/ai-crm-agent/blob/main/agent/outreach.py"
click node_followup_worker "https://github.com/lucas-m-fr/ai-crm-agent/blob/main/workers/follow_up.py"
click node_inbox_reader "https://github.com/lucas-m-fr/ai-crm-agent/blob/main/agent/inbox_reader.py"
click node_intent_classifier "https://github.com/lucas-m-fr/ai-crm-agent/blob/main/agent/classifier.py"
click node_guardrails "https://github.com/lucas-m-fr/ai-crm-agent/blob/main/db/guardrails.py"
click node_crm_store "https://github.com/lucas-m-fr/ai-crm-agent/blob/main/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_demo,node_followup_worker toneBlue
class node_outreach_sender toneAmber
class node_inbox_reader,node_intent_classifier toneMint
class node_guardrails,node_crm_store toneRose
class node_operator toneIndigo
```

## Components

### Workflow orchestration

- [Demo runner](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/main.py): `main.py`
- [Follow-up worker](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/workers/follow_up.py): `workers/follow_up.py`

### Outbound outreach

- [Outreach sender](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/agent/outreach.py): `agent/outreach.py`

### Reply processing

- [Inbox reader](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/agent/inbox_reader.py): `agent/inbox_reader.py`
- [Intent classifier](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/agent/classifier.py): `agent/classifier.py`

### Lifecycle and persistence

- [Suppression guardrails](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/db/guardrails.py): `db/guardrails.py`
- [CRM database](https://github.com/lucas-m-fr/ai-crm-agent/blob/main/db/database.py): `db/database.py`

### Other components

- **CLI operator**

## Connections

- CLI operator → Demo runner: runs (evidence: `README.md`)
- Demo runner → CRM database: initializes and seeds (evidence: `main.py`)
- Demo runner → Outreach sender: starts outreach (evidence: `main.py`)
- Demo runner → Inbox reader: simulates replies (evidence: `main.py`)
- Demo runner → Follow-up worker: runs worker (evidence: `main.py`)
- Outreach sender → Suppression guardrails: checks suppression (evidence: `agent/outreach.py`)
- Outreach sender → CRM database: reads and updates (evidence: `agent/outreach.py`)
- Suppression guardrails → CRM database: reads and writes (evidence: `db/guardrails.py`)
- Inbox reader → CRM database: matches and updates (evidence: `agent/inbox_reader.py`)
- Inbox reader → Intent classifier: classifies body (evidence: `agent/inbox_reader.py`)
- Inbox reader → Suppression guardrails: records opt-out (evidence: `agent/inbox_reader.py`)
- Follow-up worker → CRM database: queries stale prospects (evidence: `workers/follow_up.py`)
- Follow-up worker → Outreach sender: delegates sending (evidence: `workers/follow_up.py`)