# lucasdoreac/sober architecture

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

- Interactive diagram: https://gitdiagram.com/lucasdoreac/sober
- Repository: https://github.com/lucasdoreac/sober

## Overview

1. **Repository purpose**
   - This is a self-hosted “control plane” for a personal AI system.
   - The architecture is centered on two ingress paths: a **Streamlit web UI** for dashboards/chat and a **WhatsApp ingress** through **WAHA**.
   - Both paths terminate in the same **FastAPI backend**, which is the orchestration boundary.

2. **Primary runtime split**
   - **`frontend/`** runs the Streamlit UI.
   - **`app/`** runs the API layer, webhook handlers, dependency wiring, logging, and orchestration entrypoints.
   - The stack is designed for bare-metal or Docker Compose deployment, not Kubernetes.

3. **Ingress and request boundary**
   - The main backend boundary is split between **regular API chat traffic** and **WAHA webhook traffic**.
   - `app/router.py` and `app/router_waha.py` appear to define those separate ingress routes.
   - The WhatsApp path has an explicit authorization gate (“whitelist/soberania”) before any agent execution.

4. **Idempotency vs conversation state**
   - The README makes a key architectural distinction:
     - **`request_id`** = transport idempotency, preventing duplicate processing.
     - **`thread_id`** = conversational identity, used for LangGraph checkpoints and memory.
   - The `app/repositories/dedup.py` module and the `initdb/001_request_dedup.sql` schema support the dedup boundary in PostgreSQL.

5. **Orchestration core**
   - The system’s reasoning/execution layer is built around **LangGraph-style orchestration**.
   - `workflows/orchestrator.py` and `app/graph.py` are the likely composition points for the conversation graph.
   - The README indicates the graph runs asynchronously in **background tasks** so webhook responses return quickly.

6. **Agent architecture**
   - `agents/` contains a multi-role agent set: commercial, concierge, executor, financeiro, fiscal, pm, qa, supervisor, sustentacao.
   - `agents/base.py` suggests a common agent contract, with the specialized files implementing role-specific behavior.
   - `prompts/*.md` holds the role prompts, so behavior is split between code and prompt assets.

7. **Tool and integration layer**
   - `integrations/` is the external-system boundary for business systems: CRM, billing, fiscal, and WhatsApp.
   - `mcp_servers/` exposes at least CRM and WhatsApp capability through MCP-style servers, which is a separate tool-access layer for agents.
   - `app/mcp_client.py` likely connects the graph/agents to those servers.

8. **WhatsApp egress/inbound bridge**
   - The WhatsApp engine is **WAHA** (self-hosted WhatsApp API).
   - `app/services/waha_client.py` is the outbound client used by the backend to send WhatsApp messages back to the user.
   - `app/router_waha.py` is the inbound webhook endpoint from WAHA to the API.

9. **Persistence and state**
   - **PostgreSQL** is the main transactional store for dedup, LangGraph checkpoints, and audit-related state.
   - `initdb/` contains schema initialization/migrations for agency/request dedup/thread interventions.
   - **Qdrant** is part of the architecture as the vector store for RAG and long-term memory, per the README.
   - The repo also mentions **Ollama** and **Groq** as inference backends, implying model execution is abstracted behind the orchestration layer.

10. **Frontend shape**
    - `frontend/app.py` is the Streamlit entrypoint.
    - `frontend/pages/` is organized as operational dashboards rather than a single chat screen: fleets, approvals, projects, agents, contacts, payments, incidents.
    - `frontend/utils/api.py` suggests the UI is a thin client over the FastAPI backend, not a separate business logic tier.

11. **Cross-cutting concerns**
    - `app/logging_async.py` and `app/watchdog.py` indicate operational support for async logging and health/watchdog behavior.
    - `app/dependencies.py` and `app/config.py` centralize runtime wiring and environment-driven configuration.
    - The architecture favors explicit dependency injection and boundary checks over hidden framework magic.

12. **Deployment and operational model**
    - `docker-compose.yml`, `Dockerfile`, and `Dockerfile.frontend` define a multi-service deployment.
    - The README’s volume layout shows persistent state for Postgres, Qdrant, Ollama, and WAHA.
    - This is an infra-heavy application where data durability and service isolation are first-class concerns.

13. **Quality and verification**
    - `tests/` covers dependencies, routing, sustentacao behavior, and watchdog logic.
    - Utility scripts like `audit_deps.py`, `check_routes.py`, and `diagnostico_sober.py` suggest the repo includes built-in architecture/health checks.

14. **What an architecture diagram should emphasize**
    - Draw the system as two user-facing ingress channels into one FastAPI control plane.
    - Show the control plane splitting into: authorization/dedup, async orchestration, agent/tool execution, and external persistence/model services.
    - Make the `request_id` and `thread_id` separation explicit, because it is central to correctness here.

Main entry points: [`app/graph.py`](https://github.com/lucasdoreac/sober/blob/main/app/graph.py) (Orchestrator), [`app/main.py`](https://github.com/lucasdoreac/sober/blob/main/app/main.py) (API app), [`docker-compose.yml`](https://github.com/lucasdoreac/sober/blob/main/docker-compose.yml) (Compose deploy), [`app/router.py`](https://github.com/lucasdoreac/sober/blob/main/app/router.py) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_frontend["Frontend"]
  node_frontend_app["Streamlit UI<br/>frontend entry<br/>[app.py]"]
  node_frontend_pages["Dashboards<br/>ui pages"]
  node_frontend_api["API client<br/>ui backend client<br/>[api.py]"]
end

subgraph group_grp_control["FastAPI control plane"]
  node_api_main["API app<br/>[main.py]"]
  node_api_config["Config<br/>[config.py]"]
  node_api_deps["Dependencies<br/>wiring<br/>[dependencies.py]"]
  node_api_router["API routes<br/>ingress routes<br/>[router.py]"]
  node_waha_router["WAHA webhook<br/>whatsapp ingress<br/>[router_waha.py]"]
end

subgraph group_grp_orchestration["Orchestration"]
  node_graph_core{{"Orchestrator<br/>langgraph core<br/>[graph.py]"}}
  node_workflow_orch["Workflow engine<br/>async orchestration<br/>[orchestrator.py]"]
end

subgraph group_grp_agents["Agents"]
  node_agent_base["Agent base<br/>agent contract<br/>[base.py]"]
  node_agent_roles["Role agents<br/>specialized agents"]
  node_prompts_assets["Prompts<br/>prompt assets"]
end

subgraph group_grp_integrations["Integrations"]
  node_mcp_client["MCP client<br/>tool bridge<br/>[mcp_client.py]"]
  node_mcp_servers["MCP servers<br/>tool servers"]
  node_biz_integrations["Business systems<br/>external integrations"]
  node_waha_client["WAHA client<br/>whatsapp egress<br/>[waha_client.py]"]
end

subgraph group_grp_state["State"]
  node_request_dedup[("Request dedup<br/>idempotency store<br/>[dedup.py]")]
  node_thread_state[("Thread state<br/>conversation memory")]
  node_postgres[("PostgreSQL<br/>transactional store")]
  node_qdrant[("Qdrant<br/>vector store")]
  node_model_backends["Model backends<br/>llm runtime"]
end

subgraph group_grp_ops["Ops"]
  node_logging_watchdog["Ops hooks<br/>observability<br/>[logging_async.py]"]
  node_deploy_stack["Compose deploy<br/>deployment<br/>[docker-compose.yml]"]
  node_checks["Checks<br/>verification"]
end

node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_api -->|"requests"| node_api_router
node_api_main -->|"mounts"| node_api_router
node_api_main -->|"mounts"| node_waha_router
node_api_main -->|"loads"| node_api_config
node_api_main -->|"wires"| node_api_deps
node_api_router -->|"enters"| node_graph_core
node_waha_router -->|"checks"| node_request_dedup
node_waha_router -->|"dispatches"| node_graph_core
node_request_dedup -->|"persists"| node_postgres
node_graph_core -->|"runs"| node_workflow_orch
node_graph_core -->|"tracks"| node_thread_state
node_workflow_orch -->|"invokes"| node_agent_base
node_agent_base -->|"specializes"| node_agent_roles
node_agent_roles -->|"uses"| node_prompts_assets
node_agent_roles -->|"tools"| node_mcp_client
node_mcp_client -->|"connects"| node_mcp_servers
node_mcp_servers -->|"exposes"| node_biz_integrations
node_graph_core -->|"responds"| node_waha_client
node_graph_core -->|"queries"| node_model_backends
node_graph_core -->|"retrieves"| node_qdrant
node_logging_watchdog -->|"supports"| node_api_main
node_deploy_stack -->|"runs"| node_api_main
node_deploy_stack -->|"runs"| node_frontend_app
node_deploy_stack -->|"persists"| node_postgres
node_deploy_stack -->|"persists"| node_qdrant
node_checks -->|"verifies"| node_api_router
node_checks -->|"verifies"| node_logging_watchdog

click node_frontend_app "https://github.com/lucasdoreac/sober/blob/main/frontend/app.py"
click node_frontend_pages "https://github.com/lucasdoreac/sober/tree/main/frontend/pages"
click node_frontend_api "https://github.com/lucasdoreac/sober/blob/main/frontend/utils/api.py"
click node_api_main "https://github.com/lucasdoreac/sober/blob/main/app/main.py"
click node_api_config "https://github.com/lucasdoreac/sober/blob/main/app/config.py"
click node_api_deps "https://github.com/lucasdoreac/sober/blob/main/app/dependencies.py"
click node_api_router "https://github.com/lucasdoreac/sober/blob/main/app/router.py"
click node_waha_router "https://github.com/lucasdoreac/sober/blob/main/app/router_waha.py"
click node_graph_core "https://github.com/lucasdoreac/sober/blob/main/app/graph.py"
click node_workflow_orch "https://github.com/lucasdoreac/sober/blob/main/workflows/orchestrator.py"
click node_request_dedup "https://github.com/lucasdoreac/sober/blob/main/app/repositories/dedup.py"
click node_thread_state "https://github.com/lucasdoreac/sober/blob/main/initdb/005_thread_interventions.sql"
click node_agent_base "https://github.com/lucasdoreac/sober/blob/main/agents/base.py"
click node_agent_roles "https://github.com/lucasdoreac/sober/tree/main/agents"
click node_prompts_assets "https://github.com/lucasdoreac/sober/tree/main/prompts"
click node_mcp_client "https://github.com/lucasdoreac/sober/blob/main/app/mcp_client.py"
click node_mcp_servers "https://github.com/lucasdoreac/sober/tree/main/mcp_servers"
click node_biz_integrations "https://github.com/lucasdoreac/sober/tree/main/integrations"
click node_waha_client "https://github.com/lucasdoreac/sober/blob/main/app/services/waha_client.py"
click node_postgres "https://github.com/lucasdoreac/sober/tree/main/initdb"
click node_logging_watchdog "https://github.com/lucasdoreac/sober/blob/main/app/logging_async.py"
click node_deploy_stack "https://github.com/lucasdoreac/sober/blob/main/docker-compose.yml"
click node_checks "https://github.com/lucasdoreac/sober/tree/main/tests"

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_frontend_app,node_frontend_pages,node_frontend_api,node_logging_watchdog,node_deploy_stack,node_checks toneBlue
class node_api_main,node_api_config,node_api_deps,node_api_router,node_waha_router toneAmber
class node_graph_core,node_workflow_orch toneMint
class node_agent_base,node_agent_roles,node_prompts_assets toneRose
class node_mcp_client,node_mcp_servers,node_biz_integrations,node_waha_client toneIndigo
class node_request_dedup,node_thread_state,node_postgres,node_qdrant,node_model_backends toneTeal
```

## Components

### Frontend

Streamlit dashboards and thin API client.

- [Streamlit UI](https://github.com/lucasdoreac/sober/blob/main/frontend/app.py): frontend entry · Main Streamlit entrypoint for dashboards and chat. · `frontend/app.py`
- [Dashboards](https://github.com/lucasdoreac/sober/tree/main/frontend/pages): ui pages · Operational pages for fleets, approvals, projects, agents, contacts, payments, and incidents. · `frontend/pages`
- [API client](https://github.com/lucasdoreac/sober/blob/main/frontend/utils/api.py): ui backend client · Thin client used by the UI to call the FastAPI backend. · `frontend/utils/api.py`

### FastAPI control plane

Ingress, dependency wiring, auth, and orchestration boundary.

- [API app](https://github.com/lucasdoreac/sober/blob/main/app/main.py): fastapi app · Backend application bootstrap and runtime entrypoint. · `app/main.py`
- [Config](https://github.com/lucasdoreac/sober/blob/main/app/config.py): runtime config · Environment-driven configuration and settings. · `app/config.py`
- [Dependencies](https://github.com/lucasdoreac/sober/blob/main/app/dependencies.py): wiring · Dependency injection and service wiring for the backend. · `app/dependencies.py`
- [API routes](https://github.com/lucasdoreac/sober/blob/main/app/router.py): ingress routes · Regular API ingress for chat and control traffic. · `app/router.py`
- [WAHA webhook](https://github.com/lucasdoreac/sober/blob/main/app/router_waha.py): whatsapp ingress · Inbound webhook boundary from WAHA into the backend. · `app/router_waha.py`

### Orchestration

Conversation graph, background execution, and agent coordination.

- [Orchestrator](https://github.com/lucasdoreac/sober/blob/main/app/graph.py): langgraph core · Conversation graph composition and orchestration boundary. · `app/graph.py`
- [Workflow engine](https://github.com/lucasdoreac/sober/blob/main/workflows/orchestrator.py): async orchestration · Runs graph execution and background task coordination. · `workflows/orchestrator.py`

### Agents

Role-specific agents plus shared agent contract and prompts.

- [Agent base](https://github.com/lucasdoreac/sober/blob/main/agents/base.py): agent contract · Shared contract used by specialized role agents. · `agents/base.py`
- [Role agents](https://github.com/lucasdoreac/sober/tree/main/agents): specialized agents · Commercial, concierge, executor, financeiro, fiscal, pm, qa, supervisor, and sustentacao roles. · `agents`
- [Prompts](https://github.com/lucasdoreac/sober/tree/main/prompts): prompt assets · Role prompt definitions that shape agent behavior. · `prompts`

### Integrations

External business systems and MCP tool servers.

- [MCP client](https://github.com/lucasdoreac/sober/blob/main/app/mcp_client.py): tool bridge · Backend client connecting orchestration to MCP servers. · `app/mcp_client.py`
- [MCP servers](https://github.com/lucasdoreac/sober/tree/main/mcp_servers): tool servers · CRM and WhatsApp capability exposed through MCP-style servers. · `mcp_servers`
- [Business systems](https://github.com/lucasdoreac/sober/tree/main/integrations): external integrations · CRM, billing, fiscal, and WhatsApp integration layer. · `integrations`
- [WAHA client](https://github.com/lucasdoreac/sober/blob/main/app/services/waha_client.py): whatsapp egress · Outbound WhatsApp client used to send messages back to users. · `app/services/waha_client.py`

### State

Database, deduplication, checkpoints, and vector memory.

- [Request dedup](https://github.com/lucasdoreac/sober/blob/main/app/repositories/dedup.py): idempotency store · Transport-level duplicate suppression keyed by request_id. · `app/repositories/dedup.py`
- [Thread state](https://github.com/lucasdoreac/sober/blob/main/initdb/005_thread_interventions.sql): conversation memory · Conversation identity and checkpoint state keyed by thread_id. · `initdb/005_thread_interventions.sql`
- [PostgreSQL](https://github.com/lucasdoreac/sober/tree/main/initdb): transactional store · Persistent store for dedup, agency schema, checkpoints, and audit-related state. · `initdb`
- **Qdrant**: vector store · Vector store for RAG and long-term memory.
- **Model backends**: llm runtime · Ollama and Groq inference backends used behind the orchestration layer.

### Ops

Logging, watchdogs, deployment, and verification utilities.

- [Ops hooks](https://github.com/lucasdoreac/sober/blob/main/app/logging_async.py): observability · Async logging and watchdog health behavior. · `app/logging_async.py`
- [Compose deploy](https://github.com/lucasdoreac/sober/blob/main/docker-compose.yml): deployment · Docker Compose and container build setup for the self-hosted stack. · `docker-compose.yml`
- [Checks](https://github.com/lucasdoreac/sober/tree/main/tests): verification · Dependency, route, sustention, and watchdog verification scripts/tests. · `tests`

## Connections

- Streamlit UI → Dashboards: renders · The Streamlit entrypoint hosts the dashboard pages.
- Streamlit UI → API client: calls · UI actions go through the API client.
- API client → API routes: requests · Thin client sends user traffic to the backend ingress.
- API app → API routes: mounts · Primary API app exposes the regular routes.
- API app → WAHA webhook: mounts · Primary API app exposes the WAHA webhook routes.
- API app → Config: loads · Runtime configuration is centralized here.
- API app → Dependencies: wires · Dependency injection and services are assembled here.
- API routes → Orchestrator: enters · Regular chat/control requests hand off to orchestration.
- WAHA webhook → Request dedup: checks · Webhook traffic is deduplicated by request_id.
- WAHA webhook → Orchestrator: dispatches · Authorized WAHA events are forwarded into the orchestration graph.
- Request dedup → PostgreSQL: persists · Dedup state is stored in PostgreSQL.
- Orchestrator → Workflow engine: runs · The graph is executed asynchronously in background tasks.
- Orchestrator → Thread state: tracks · Conversation identity and checkpoints follow thread_id.
- Workflow engine → Agent base: invokes · Orchestration executes agent contracts.
- Agent base → Role agents: specializes · Specialized role agents implement the shared base.
- Role agents → Prompts: uses · Behavior is partly defined by prompt assets.
- Role agents → MCP client: tools · Agents access external capabilities through the MCP bridge.
- MCP client → MCP servers: connects · Client reaches the CRM and WhatsApp tool servers.
- MCP servers → Business systems: exposes · Tool servers wrap business system integrations.
- Orchestrator → WAHA client: responds · Outbound WhatsApp messages are sent back through the WAHA client.
- Orchestrator → Model backends: queries · LLM execution is abstracted behind the orchestration layer.
- Orchestrator → Qdrant: retrieves · Vector memory and RAG lookups use Qdrant.
- Ops hooks → API app: supports · Operational hooks cover async logging and health monitoring.
- Compose deploy → API app: runs · Compose and container files define the backend service.
- Compose deploy → Streamlit UI: runs · Compose and container files define the frontend service.
- Compose deploy → PostgreSQL: persists · Persistent database volumes back the stack.
- Compose deploy → Qdrant: persists · Persistent vector-store volumes back the stack.
- Checks → API routes: verifies · Repository checks validate routing behavior.
- Checks → Ops hooks: verifies · Repository checks validate watchdog behavior.