# t0mer/openwa_llm architecture

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

- Interactive diagram: https://gitdiagram.com/t0mer/openwa_llm
- Repository: https://github.com/t0mer/openwa_llm

## Overview

OpenWA LLM is a WhatsApp group bot with an authenticated admin console. Incoming WhatsApp events are verified and dispatched into message handling, while separate ingestion and scheduled/API summary workflows use stored conversation history and AI-generated output. Knowledge-base ingestion embeds extracted topics for later context-aware answers. The admin UI manages groups, contacts, messages, opt-outs, schedules, actions, and connection settings. Several route and storage implementations were not sampled; their presence and capabilities are reflected from the tree and README, but unverified internal links are omitted.

Main entry points: [`src/handler/router.py`](https://github.com/t0mer/openwa_llm/blob/main/src/handler/router.py) (Message handling), [`src/summarize_and_send_to_groups/__init__.py`](https://github.com/t0mer/openwa_llm/blob/main/src/summarize_and_send_to_groups/__init__.py) (Group summaries), [`src/whatsapp/gateway.py`](https://github.com/t0mer/openwa_llm/blob/main/src/whatsapp/gateway.py) (WhatsApp gateway), [`src/models/message.py`](https://github.com/t0mer/openwa_llm/blob/main/src/models/message.py) (Conversation and domain models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Webhook and handling"]
  node_webhook["Webhook verification<br/>[webhook.py]"]
  node_event_handler["Message handling<br/>[router.py]"]
  node_base_handler["Base handler<br/>[base_handler.py]"]
  node_spam_handler["Group-link spam"]
end

subgraph group_knowledge["Knowledge and answers"]
  node_kb_answers["Knowledge answers"]
  node_kb_qa["Knowledge Q&amp;A<br/>[kb_qa.py]"]
  node_kb_ingest["Topic extraction<br/>[__init__.py]"]
  node_hybrid_search["Hybrid search<br/>[hybrid_search.py]"]
end

subgraph group_summary["Summaries and scheduling"]
  node_summary_job["Group summaries<br/>[__init__.py]"]
  node_scheduler["Summary scheduler<br/>[runner.py]"]
  node_api_routes["Summary and ingest APIs"]
end

subgraph group_admin["Administration"]
  node_admin_router["Admin routes<br/>[router.py]"]
  node_admin_actions["Admin actions<br/>[actions.py]"]
  node_admin_auth["Admin authentication<br/>[auth_routes.py]"]
  node_admin_web["Admin console<br/>[App.tsx]"]
end

subgraph group_infra["WhatsApp and state"]
  node_gateway["WhatsApp gateway<br/>[gateway.py]"]
  node_openwa_gateway["OpenWA adapter<br/>[openwa.py]"]
  node_registry["Session registry<br/>[registry.py]"]
  node_settings_store["Encrypted settings<br/>[store.py]"]
  node_models["Conversation and domain models<br/>[message.py]"]
  node_prompt_manager["Prompt templates<br/>[prompt_manager.py]"]
  node_jid["WhatsApp identity parsing<br/>[jid.py]"]
end

node_wa_user(("WhatsApp participants"))
node_admin_user(("Admin operator"))
node_openwa_service["OpenWA service"]
node_llm["LLM provider"]
node_voyage["Voyage embeddings"]
node_postgres[("PostgreSQL pgvector")]

node_wa_user -->|"sends messages"| node_openwa_service
node_openwa_service -->|"posts events"| node_webhook
node_webhook -->|"dispatches events"| node_event_handler
node_webhook -->|"syncs groups"| node_gateway
node_event_handler -->|"delegates to"| node_base_handler
node_event_handler -->|"routes answers"| node_kb_answers
node_event_handler -.->|"checks links"| node_spam_handler
node_kb_answers -.->|"uses Q&amp;A"| node_kb_qa
node_kb_answers -.->|"searches context"| node_hybrid_search
node_kb_ingest -->|"embeds topics"| node_voyage
node_kb_ingest -->|"stores topics"| node_models
node_hybrid_search -->|"reads topic links"| node_models
node_event_handler -->|"renders prompts"| node_prompt_manager
node_summary_job -->|"renders prompts"| node_prompt_manager
node_summary_job -->|"sends summaries"| node_gateway
node_scheduler -->|"runs summaries"| node_summary_job
node_api_routes -.->|"triggers summaries"| node_summary_job
node_summary_job -->|"generates summaries"| node_llm
node_admin_user -->|"uses console"| node_admin_web
node_admin_web -.->|"calls admin API"| node_admin_router
node_admin_router -->|"registers auth routes"| node_admin_auth
node_admin_router -->|"registers actions"| node_admin_actions
node_admin_actions -->|"controls sessions"| node_gateway
node_registry -->|"creates gateways"| node_openwa_gateway
node_openwa_gateway -->|"implements interface"| node_gateway
node_registry -->|"loads connection"| node_settings_store
node_settings_store -->|"reads settings records"| node_models
node_gateway -->|"connects to"| node_openwa_service
node_models -->|"persists history"| node_postgres
node_jid -->|"normalizes identities"| node_event_handler

click node_webhook "https://github.com/t0mer/openwa_llm/blob/main/src/api/webhook.py"
click node_event_handler "https://github.com/t0mer/openwa_llm/blob/main/src/handler/router.py"
click node_base_handler "https://github.com/t0mer/openwa_llm/blob/main/src/handler/base_handler.py"
click node_spam_handler "https://github.com/t0mer/openwa_llm/blob/main/src/handler/whatsapp_group_link_spam.py"
click node_kb_answers "https://github.com/t0mer/openwa_llm/blob/main/src/handler/knowledge_base_answers.py"
click node_kb_qa "https://github.com/t0mer/openwa_llm/blob/main/src/handler/kb_qa.py"
click node_kb_ingest "https://github.com/t0mer/openwa_llm/blob/main/src/load_new_kbtopics/__init__.py"
click node_hybrid_search "https://github.com/t0mer/openwa_llm/blob/main/src/search/hybrid_search.py"
click node_summary_job "https://github.com/t0mer/openwa_llm/blob/main/src/summarize_and_send_to_groups/__init__.py"
click node_scheduler "https://github.com/t0mer/openwa_llm/blob/main/src/scheduling/runner.py"
click node_api_routes "https://github.com/t0mer/openwa_llm/blob/main/src/api/summarize_and_send_to_group_api.py"
click node_admin_router "https://github.com/t0mer/openwa_llm/blob/main/src/admin/router.py"
click node_admin_actions "https://github.com/t0mer/openwa_llm/blob/main/src/admin/actions.py"
click node_admin_auth "https://github.com/t0mer/openwa_llm/blob/main/src/admin/auth_routes.py"
click node_admin_web "https://github.com/t0mer/openwa_llm/blob/main/web/src/App.tsx"
click node_gateway "https://github.com/t0mer/openwa_llm/blob/main/src/whatsapp/gateway.py"
click node_openwa_gateway "https://github.com/t0mer/openwa_llm/blob/main/src/whatsapp/openwa.py"
click node_registry "https://github.com/t0mer/openwa_llm/blob/main/src/openwa_settings/registry.py"
click node_settings_store "https://github.com/t0mer/openwa_llm/blob/main/src/openwa_settings/store.py"
click node_models "https://github.com/t0mer/openwa_llm/blob/main/src/models/message.py"
click node_prompt_manager "https://github.com/t0mer/openwa_llm/blob/main/src/services/prompt_manager.py"
click node_jid "https://github.com/t0mer/openwa_llm/blob/main/src/whatsapp/jid.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_webhook,node_event_handler,node_base_handler,node_spam_handler toneBlue
class node_kb_answers,node_kb_qa,node_kb_ingest,node_hybrid_search,node_postgres toneAmber
class node_summary_job,node_scheduler,node_api_routes toneMint
class node_admin_router,node_admin_actions,node_admin_auth,node_admin_web toneRose
class node_gateway,node_openwa_gateway,node_registry,node_settings_store,node_models,node_prompt_manager,node_jid,node_wa_user,node_admin_user,node_openwa_service,node_llm,node_voyage toneIndigo
```

## Components

### Webhook and handling

- [Webhook verification](https://github.com/t0mer/openwa_llm/blob/main/src/api/webhook.py): `src/api/webhook.py`
- [Message handling](https://github.com/t0mer/openwa_llm/blob/main/src/handler/router.py): `src/handler/router.py`
- [Base handler](https://github.com/t0mer/openwa_llm/blob/main/src/handler/base_handler.py): `src/handler/base_handler.py`
- [Group-link spam](https://github.com/t0mer/openwa_llm/blob/main/src/handler/whatsapp_group_link_spam.py): `src/handler/whatsapp_group_link_spam.py`

### Knowledge and answers

- [Knowledge answers](https://github.com/t0mer/openwa_llm/blob/main/src/handler/knowledge_base_answers.py): `src/handler/knowledge_base_answers.py`
- [Knowledge Q&A](https://github.com/t0mer/openwa_llm/blob/main/src/handler/kb_qa.py): `src/handler/kb_qa.py`
- [Topic extraction](https://github.com/t0mer/openwa_llm/blob/main/src/load_new_kbtopics/__init__.py): `src/load_new_kbtopics/__init__.py`
- [Hybrid search](https://github.com/t0mer/openwa_llm/blob/main/src/search/hybrid_search.py): `src/search/hybrid_search.py`

### Summaries and scheduling

- [Group summaries](https://github.com/t0mer/openwa_llm/blob/main/src/summarize_and_send_to_groups/__init__.py): `src/summarize_and_send_to_groups/__init__.py`
- [Summary scheduler](https://github.com/t0mer/openwa_llm/blob/main/src/scheduling/runner.py): `src/scheduling/runner.py`
- [Summary and ingest APIs](https://github.com/t0mer/openwa_llm/blob/main/src/api/summarize_and_send_to_group_api.py): `src/api/summarize_and_send_to_group_api.py`

### Administration

- [Admin routes](https://github.com/t0mer/openwa_llm/blob/main/src/admin/router.py): `src/admin/router.py`
- [Admin actions](https://github.com/t0mer/openwa_llm/blob/main/src/admin/actions.py): `src/admin/actions.py`
- [Admin authentication](https://github.com/t0mer/openwa_llm/blob/main/src/admin/auth_routes.py): `src/admin/auth_routes.py`
- [Admin console](https://github.com/t0mer/openwa_llm/blob/main/web/src/App.tsx): `web/src/App.tsx`

### WhatsApp and state

- [WhatsApp gateway](https://github.com/t0mer/openwa_llm/blob/main/src/whatsapp/gateway.py): `src/whatsapp/gateway.py`
- [OpenWA adapter](https://github.com/t0mer/openwa_llm/blob/main/src/whatsapp/openwa.py): `src/whatsapp/openwa.py`
- [Session registry](https://github.com/t0mer/openwa_llm/blob/main/src/openwa_settings/registry.py): `src/openwa_settings/registry.py`
- [Encrypted settings](https://github.com/t0mer/openwa_llm/blob/main/src/openwa_settings/store.py): `src/openwa_settings/store.py`
- [Conversation and domain models](https://github.com/t0mer/openwa_llm/blob/main/src/models/message.py): `src/models/message.py`
- [Prompt templates](https://github.com/t0mer/openwa_llm/blob/main/src/services/prompt_manager.py): `src/services/prompt_manager.py`
- [WhatsApp identity parsing](https://github.com/t0mer/openwa_llm/blob/main/src/whatsapp/jid.py): `src/whatsapp/jid.py`

### Other components

- **WhatsApp participants**
- **Admin operator**
- **OpenWA service**
- **LLM provider**
- **Voyage embeddings**
- **PostgreSQL pgvector**

## Connections

- WhatsApp participants → OpenWA service: sends messages
- OpenWA service → Webhook verification: posts events
- Webhook verification → Message handling: dispatches events (evidence: `src/api/webhook.py`)
- Webhook verification → WhatsApp gateway: syncs groups (evidence: `src/api/webhook.py`)
- Message handling → Base handler: delegates to (evidence: `src/handler/router.py`)
- Message handling → Knowledge answers: routes answers (evidence: `src/handler/router.py`)
- Message handling → Group-link spam: checks links
- Knowledge answers → Knowledge Q&A: uses Q&A
- Knowledge answers → Hybrid search: searches context
- Topic extraction → Voyage embeddings: embeds topics (evidence: `src/load_new_kbtopics/__init__.py`)
- Topic extraction → Conversation and domain models: stores topics (evidence: `src/load_new_kbtopics/__init__.py`)
- Hybrid search → Conversation and domain models: reads topic links (evidence: `src/search/hybrid_search.py`)
- Message handling → Prompt templates: renders prompts (evidence: `src/handler/router.py`)
- Group summaries → Prompt templates: renders prompts (evidence: `src/summarize_and_send_to_groups/__init__.py`)
- Group summaries → WhatsApp gateway: sends summaries (evidence: `src/summarize_and_send_to_groups/__init__.py`)
- Summary scheduler → Group summaries: runs summaries (evidence: `src/scheduling/runner.py`)
- Summary and ingest APIs → Group summaries: triggers summaries
- Group summaries → LLM provider: generates summaries
- Admin operator → Admin console: uses console
- Admin console → Admin routes: calls admin API
- Admin routes → Admin authentication: registers auth routes (evidence: `src/admin/router.py`)
- Admin routes → Admin actions: registers actions (evidence: `src/admin/router.py`)
- Admin actions → WhatsApp gateway: controls sessions (evidence: `src/admin/actions.py`)
- Session registry → OpenWA adapter: creates gateways (evidence: `src/openwa_settings/registry.py`)
- OpenWA adapter → WhatsApp gateway: implements interface (evidence: `src/whatsapp/__init__.py`)
- Session registry → Encrypted settings: loads connection (evidence: `src/openwa_settings/registry.py`)
- Encrypted settings → Conversation and domain models: reads settings records (evidence: `src/openwa_settings/store.py`)
- WhatsApp gateway → OpenWA service: connects to
- Conversation and domain models → PostgreSQL pgvector: persists history
- WhatsApp identity parsing → Message handling: normalizes identities (evidence: `src/handler/router.py`)