# kevinrivm/nea-agent architecture

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

- Interactive diagram: https://gitdiagram.com/kevinrivm/nea-agent
- Repository: https://github.com/kevinrivm/nea-agent

## Overview

Nea is a self-hosted conversational scheduling agent for CRM-dispatched social messages. Its main path is durable dispatch intake, then a conversational turn that obtains CRM context, consults the business profile, uses an LLM and tools, and replies through the CRM. Scheduling, media understanding, follow-up, escalation, and durable retries are distinct capabilities. The excerpts establish the dispatch and turn flow; some auxiliary links rely on README descriptions or source-index references, so unsampled implementation details are not inferred.

Main entry points: [`app/turn.py`](https://github.com/kevinrivm/nea-agent/blob/main/app/turn.py) (Turn orchestrator), [`app/crm.py`](https://github.com/kevinrivm/nea-agent/blob/main/app/crm.py) (CRM API client), [`app/main.py`](https://github.com/kevinrivm/nea-agent/blob/main/app/main.py) (FastAPI runtime), [`app/dispatch.py`](https://github.com/kevinrivm/nea-agent/blob/main/app/dispatch.py) (Dispatch intake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Dispatch and runtime"]
  node_dispatch["Dispatch intake<br/>[dispatch.py]"]
  node_app_runtime["FastAPI runtime<br/>[main.py]"]
end

subgraph group_conversation["Conversation behavior"]
  node_turn["Turn orchestrator<br/>[turn.py]"]
  node_llm["LLM client<br/>[llm.py]"]
  node_prompt["Prompt builder<br/>[prompt.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_media["Media processing<br/>[media.py]"]
  node_format["Message formatting<br/>[formato.py]"]
  node_hostility["Hostility rules<br/>[hostility.py]"]
  node_stall["Stall handling<br/>[stall.py]"]
end

subgraph group_crm["CRM and business context"]
  node_agenda["Agenda probing<br/>[agenda.py]"]
  node_crm_client["CRM API client<br/>[crm.py]"]
  node_cloud_client["Cloud CRM client<br/>[crm_brains.py]"]
  node_profile["Business profile<br/>[profile.py]"]
  node_multi_org["Organization routing<br/>[multiorg.py]"]
  node_rehearsal["Agent rehearsal<br/>[ensayo.py]"]
end

subgraph group_state["State and reliability"]
  node_store_contract["Conversation state<br/>[state.py]"]
  node_postgres[("Postgres store<br/>[db.py]")]
  node_dispatch_store["Dispatch inbox<br/>[dispatch_store.py]"]
  node_dispatch_worker["Dispatch worker<br/>[dispatch_worker.py]"]
  node_followup["Follow-up worker<br/>[followup.py]"]
  node_sender["Pending sender<br/>[sender.py]"]
end

node_crm_user(("Business lead"))
node_crm_service["Vocero CRM"]

node_crm_service -->|"dispatches messages"| node_dispatch
node_dispatch -->|"persists dispatch"| node_dispatch_store
node_dispatch -->|"queues turn"| node_turn
node_app_runtime -->|"registers intake"| node_dispatch
node_app_runtime -->|"starts worker"| node_dispatch_worker
node_dispatch_worker -->|"processes inbox"| node_dispatch
node_turn -->|"gets context"| node_crm_client
node_turn -->|"runs completion"| node_llm
node_turn -->|"executes tool calls"| node_tools
node_turn -->|"builds prompt"| node_prompt
node_turn -->|"processes inbound media"| node_media
node_turn -->|"formats reply"| node_format
node_turn -->|"checks hostility"| node_hostility
node_turn -->|"checks stalled state"| node_stall
node_turn -->|"reads and updates state"| node_store_contract
node_tools -->|"calls CRM actions"| node_crm_client
node_tools -->|"checks agenda"| node_agenda
node_profile -->|"loads profile"| node_crm_client
node_prompt -->|"uses business profile"| node_profile
node_crm_client -->|"requests bot API"| node_crm_service
node_cloud_client -->|"requests brains API"| node_crm_service
node_multi_org -->|"creates org clients"| node_cloud_client
node_multi_org -->|"provides org profile"| node_profile
node_rehearsal -->|"reuses turn flow"| node_turn
node_rehearsal -->|"reads CRM data"| node_cloud_client
node_store_contract -->|"implemented by"| node_postgres
node_postgres -->|"uses inbox storage"| node_dispatch_store
node_app_runtime -->|"connects and migrates"| node_postgres
node_app_runtime -->|"starts follow-up"| node_followup
node_app_runtime -->|"starts pending sender"| node_sender
node_followup -->|"gets context"| node_crm_client
node_sender -->|"sends pending replies"| node_crm_client
node_crm_service -->|"delivers replies"| node_crm_user

click node_dispatch "https://github.com/kevinrivm/nea-agent/blob/main/app/dispatch.py"
click node_app_runtime "https://github.com/kevinrivm/nea-agent/blob/main/app/main.py"
click node_turn "https://github.com/kevinrivm/nea-agent/blob/main/app/turn.py"
click node_llm "https://github.com/kevinrivm/nea-agent/blob/main/app/llm.py"
click node_prompt "https://github.com/kevinrivm/nea-agent/blob/main/app/prompt.py"
click node_tools "https://github.com/kevinrivm/nea-agent/blob/main/app/tools.py"
click node_media "https://github.com/kevinrivm/nea-agent/blob/main/app/media.py"
click node_format "https://github.com/kevinrivm/nea-agent/blob/main/app/formato.py"
click node_hostility "https://github.com/kevinrivm/nea-agent/blob/main/app/hostility.py"
click node_stall "https://github.com/kevinrivm/nea-agent/blob/main/app/stall.py"
click node_agenda "https://github.com/kevinrivm/nea-agent/blob/main/app/agenda.py"
click node_crm_client "https://github.com/kevinrivm/nea-agent/blob/main/app/crm.py"
click node_cloud_client "https://github.com/kevinrivm/nea-agent/blob/main/app/crm_brains.py"
click node_profile "https://github.com/kevinrivm/nea-agent/blob/main/app/profile.py"
click node_multi_org "https://github.com/kevinrivm/nea-agent/blob/main/app/multiorg.py"
click node_rehearsal "https://github.com/kevinrivm/nea-agent/blob/main/app/ensayo.py"
click node_store_contract "https://github.com/kevinrivm/nea-agent/blob/main/app/state.py"
click node_postgres "https://github.com/kevinrivm/nea-agent/blob/main/app/db.py"
click node_dispatch_store "https://github.com/kevinrivm/nea-agent/blob/main/app/dispatch_store.py"
click node_dispatch_worker "https://github.com/kevinrivm/nea-agent/blob/main/app/dispatch_worker.py"
click node_followup "https://github.com/kevinrivm/nea-agent/blob/main/app/followup.py"
click node_sender "https://github.com/kevinrivm/nea-agent/blob/main/app/sender.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_dispatch,node_app_runtime toneBlue
class node_turn,node_llm,node_prompt,node_tools,node_media,node_format,node_hostility,node_stall toneAmber
class node_agenda,node_crm_client,node_cloud_client,node_profile,node_multi_org,node_rehearsal toneMint
class node_store_contract,node_postgres,node_dispatch_store,node_dispatch_worker,node_followup,node_sender toneRose
class node_crm_user,node_crm_service toneIndigo
```

## Components

### Dispatch and runtime

- [Dispatch intake](https://github.com/kevinrivm/nea-agent/blob/main/app/dispatch.py): `app/dispatch.py`
- [FastAPI runtime](https://github.com/kevinrivm/nea-agent/blob/main/app/main.py): `app/main.py`

### Conversation behavior

- [Turn orchestrator](https://github.com/kevinrivm/nea-agent/blob/main/app/turn.py): `app/turn.py`
- [LLM client](https://github.com/kevinrivm/nea-agent/blob/main/app/llm.py): `app/llm.py`
- [Prompt builder](https://github.com/kevinrivm/nea-agent/blob/main/app/prompt.py): `app/prompt.py`
- [Agent tools](https://github.com/kevinrivm/nea-agent/blob/main/app/tools.py): `app/tools.py`
- [Media processing](https://github.com/kevinrivm/nea-agent/blob/main/app/media.py): `app/media.py`
- [Message formatting](https://github.com/kevinrivm/nea-agent/blob/main/app/formato.py): `app/formato.py`
- [Hostility rules](https://github.com/kevinrivm/nea-agent/blob/main/app/hostility.py): `app/hostility.py`
- [Stall handling](https://github.com/kevinrivm/nea-agent/blob/main/app/stall.py): `app/stall.py`

### CRM and business context

- [Agenda probing](https://github.com/kevinrivm/nea-agent/blob/main/app/agenda.py): `app/agenda.py`
- [CRM API client](https://github.com/kevinrivm/nea-agent/blob/main/app/crm.py): `app/crm.py`
- [Cloud CRM client](https://github.com/kevinrivm/nea-agent/blob/main/app/crm_brains.py): `app/crm_brains.py`
- [Business profile](https://github.com/kevinrivm/nea-agent/blob/main/app/profile.py): `app/profile.py`
- [Organization routing](https://github.com/kevinrivm/nea-agent/blob/main/app/multiorg.py): `app/multiorg.py`
- [Agent rehearsal](https://github.com/kevinrivm/nea-agent/blob/main/app/ensayo.py): `app/ensayo.py`

### State and reliability

- [Conversation state](https://github.com/kevinrivm/nea-agent/blob/main/app/state.py): `app/state.py`
- [Postgres store](https://github.com/kevinrivm/nea-agent/blob/main/app/db.py): `app/db.py`
- [Dispatch inbox](https://github.com/kevinrivm/nea-agent/blob/main/app/dispatch_store.py): `app/dispatch_store.py`
- [Dispatch worker](https://github.com/kevinrivm/nea-agent/blob/main/app/dispatch_worker.py): `app/dispatch_worker.py`
- [Follow-up worker](https://github.com/kevinrivm/nea-agent/blob/main/app/followup.py): `app/followup.py`
- [Pending sender](https://github.com/kevinrivm/nea-agent/blob/main/app/sender.py): `app/sender.py`

### Other components

- **Business lead**
- **Vocero CRM**

## Connections

- Vocero CRM → Dispatch intake: dispatches messages (evidence: `README.md`)
- Dispatch intake → Dispatch inbox: persists dispatch (evidence: `app/dispatch.py`)
- Dispatch intake → Turn orchestrator: queues turn (evidence: `app/dispatch.py`)
- FastAPI runtime → Dispatch intake: registers intake (evidence: `app/main.py`)
- FastAPI runtime → Dispatch worker: starts worker (evidence: `app/main.py`)
- Dispatch worker → Dispatch intake: processes inbox (evidence: `app/dispatch_worker.py`)
- Turn orchestrator → CRM API client: gets context (evidence: `app/turn.py`)
- Turn orchestrator → LLM client: runs completion (evidence: `app/turn.py`)
- Turn orchestrator → Agent tools: executes tool calls (evidence: `app/turn.py`)
- Turn orchestrator → Prompt builder: builds prompt (evidence: `app/turn.py`)
- Turn orchestrator → Media processing: processes inbound media (evidence: `app/turn.py`)
- Turn orchestrator → Message formatting: formats reply (evidence: `app/turn.py`)
- Turn orchestrator → Hostility rules: checks hostility (evidence: `app/turn.py`)
- Turn orchestrator → Stall handling: checks stalled state (evidence: `app/turn.py`)
- Turn orchestrator → Conversation state: reads and updates state (evidence: `app/turn.py`)
- Agent tools → CRM API client: calls CRM actions (evidence: `app/tools.py`)
- Agent tools → Agenda probing: checks agenda (evidence: `app/tools.py`)
- Business profile → CRM API client: loads profile (evidence: `app/profile.py`)
- Prompt builder → Business profile: uses business profile (evidence: `app/prompt.py`)
- CRM API client → Vocero CRM: requests bot API (evidence: `app/crm.py`)
- Cloud CRM client → Vocero CRM: requests brains API (evidence: `app/crm_brains.py`)
- Organization routing → Cloud CRM client: creates org clients (evidence: `app/multiorg.py`)
- Organization routing → Business profile: provides org profile (evidence: `app/multiorg.py`)
- Agent rehearsal → Turn orchestrator: reuses turn flow (evidence: `app/ensayo.py`)
- Agent rehearsal → Cloud CRM client: reads CRM data (evidence: `app/ensayo.py`)
- Conversation state → Postgres store: implemented by (evidence: `app/state.py`)
- Postgres store → Dispatch inbox: uses inbox storage (evidence: `app/db.py`)
- FastAPI runtime → Postgres store: connects and migrates (evidence: `app/main.py`)
- FastAPI runtime → Follow-up worker: starts follow-up (evidence: `app/main.py`)
- FastAPI runtime → Pending sender: starts pending sender (evidence: `app/main.py`)
- Follow-up worker → CRM API client: gets context (evidence: `app/followup.py`)
- Pending sender → CRM API client: sends pending replies (evidence: `app/sender.py`)
- Vocero CRM → Business lead: delivers replies (evidence: `README.md`)
