# badboydemo/kairos architecture

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

- Interactive diagram: https://gitdiagram.com/badboydemo/kairos
- Repository: https://github.com/badboydemo/kairos

## Overview

#### Purpose and Entry Points
Kairos is a Telegram-first trading automation platform: it converts unstructured group signals into structured trades, applies deterministic risk controls, and either requests user confirmation or executes through a broker. The deployable services are the FastAPI backend at `KAIROS - the product/backend/app/main.py` and the persistent Telethon listener at `KAIROS - the product/listener/main.py`. Container topology is defined in `KAIROS - the product/docker-compose.yml`.

#### Signal Ingestion and Queue Boundary
The listener joins signal groups using a user session, manages sessions, and deduplicates incoming Telegram messages before pushing work to Redis. This deliberately separates long-lived Telegram connectivity from backend deployments. Primary paths: `KAIROS - the product/listener/main.py`, `KAIROS - the product/listener/session_manager.py`, `KAIROS - the product/listener/dedup.py`. The backend consumes and assembles queued signal fragments through `KAIROS - the product/backend/app/queue/redis_consumer.py` and `KAIROS - the product/backend/app/queue/signal_assembly.py`.

#### Signal Interpretation and Routing
The signal domain parses messages, including Aurum/Pine-originated signals, then routes valid structured signals into the trade flow. Core paths: `KAIROS - the product/backend/app/signals/service.py`, `KAIROS - the product/backend/app/signals/parser.py`, `KAIROS - the product/backend/app/signals/router.py`. Hermes can contribute AI-based signal interpretation through `KAIROS - the product/backend/app/hermes/agents/signal_intelligence.py`; Claude/Anthropic is an external parsing dependency, not the authorization point.

#### Risk Gate and Trade Execution
The risk engine is the hard execution boundary: it calculates sizing and evaluates limits or halt conditions before a trade can proceed. Core paths: `KAIROS - the product/backend/app/risk/engine.py`, `KAIROS - the product/backend/app/risk/sizing.py`, `KAIROS - the product/backend/app/risk/halt.py`. Approved manual and automatic flows converge in `KAIROS - the product/backend/app/trades/service.py` and `KAIROS - the product/backend/app/trades/executor.py`, which execute via MetaApi. Broker connection pooling, synchronization, degradation, and reconciliation are isolated in `KAIROS - the product/backend/app/brokers/pool.py`, `KAIROS - the product/backend/app/brokers/sync_listener.py`, and `KAIROS - the product/backend/app/brokers/reconciliation.py`.

#### Telegram Interaction and Onboarding
Telegram is both the operational UI and callback ingress: the bot/webhook handles confirmations and notifications, while onboarding provisions identity, groups, broker connectivity, and risk preferences. Paths: `KAIROS - the product/backend/app/telegram/webhook.py`, `KAIROS - the product/backend/app/telegram/bot.py`, `KAIROS - the product/backend/app/onboarding/dispatch.py`. Notifications are emitted through `KAIROS - the product/backend/app/notifications/dispatch.py`.

#### Hermes Intelligence Layer
Hermes is the internal multi-agent orchestration layer for conversation, command handling, contextual reasoning, risk-oriented guidance, and trading management. The routing/control plane is in `KAIROS - the product/backend/app/hermes/agent_manager.py`, `KAIROS - the product/backend/app/hermes/agents/orchestrator.py`, and `KAIROS - the product/backend/app/hermes/conversation_engine.py`. Its model router abstracts provider selection, policy, fallback, cache payloads, metrics, and alerts: `KAIROS - the product/backend/app/hermes/model_router/router.py`, `KAIROS - the product/backend/app/hermes/model_router/policy.py`.

#### State, Tenancy, and Durable Memory
Supabase/Postgres is the durable system of record for users, groups, broker accounts, trades, rules, sessions, billing, notifications, and Hermes memory. Database access and tenant scoping reside in `KAIROS - the product/backend/app/db/client.py`, `KAIROS - the product/backend/app/db/scoping.py`, with schema evolution in `KAIROS - the product/supabase/migrations/0001_init_schema.sql` through `KAIROS - the product/supabase/migrations/0012_memory_weaver.sql`. Hermes memory is managed by `KAIROS - the product/backend/app/hermes/memory_manager.py`; the separate Memory Weaver synchronizes knowledge to Git/Obsidian via `KAIROS - the product/backend/app/memory_weaver/sync.py`.

#### Runtime and External Infrastructure
The runtime is Python/FastAPI plus Redis, Docker Compose, and Nginx reverse proxy configuration at `KAIROS - the product/infra/nginx/kairos.conf`. External services are Telegram (Bot API and Telethon API), Supabase, Anthropic, and MetaApi/broker accounts. Billing and subscription enforcement are backend concerns in `KAIROS - the product/backend/app/billing/limits.py`, `KAIROS - the product/backend/app/billing/metering.py`, and `KAIROS - the product/backend/app/billing/webhook.py`.

Main entry points: [`KAIROS - the product/backend/app/main.py`](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/main.py) (FastAPI Backend), [`KAIROS - the product/backend/app/trades/service.py`](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/trades/service.py) (Trade Service), [`KAIROS - the product/backend/app/db/client.py`](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/db/client.py) (Supabase / Postgres), [`KAIROS - the product/backend/app/signals/service.py`](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/signals/service.py) (Signal Interpretation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Signal Ingestion"]
  node_listener["Telethon Listener<br/>Python service<br/>[main.py]"]
  node_listener_sessions["Session &amp; Dedup<br/>listener layer<br/>[session_manager.py]"]
  node_redis["Redis Queue"]
end

subgraph group_backend["Backend Trade Flow"]
  node_signal_consumer["Signal Assembly<br/>queue consumer<br/>[signal_assembly.py]"]
  node_signal_service["Signal Interpretation<br/>signal domain<br/>[service.py]"]
  node_risk_engine{{"Risk Gate<br/>risk engine<br/>[engine.py]"}}
  node_trade_service["Trade Service<br/>trade domain<br/>[service.py]"]
  node_trade_executor["Trade Executor<br/>broker adapter<br/>[executor.py]"]
  node_broker_lifecycle["Broker Lifecycle<br/>broker operations<br/>[pool.py]"]
  node_api["FastAPI Backend<br/>API service<br/>[main.py]"]
  node_telegram_ui["Telegram Bot &amp; Webhook<br/>Telegram interface<br/>[webhook.py]"]
  node_onboarding["Onboarding<br/>provisioning flow<br/>[dispatch.py]"]
  node_billing["Billing Limits<br/>subscription enforcement<br/>[limits.py]"]
end

subgraph group_intelligence["Hermes Intelligence"]
  node_hermes["Hermes Orchestrator<br/>agent control plane<br/>[agent_manager.py]"]
  node_model_router["Model Router<br/>LLM policy layer<br/>[router.py]"]
  node_durable_memory["Hermes Memory<br/>memory manager<br/>[memory_manager.py]"]
end

subgraph group_state["State &amp; Operations"]
  node_database[("Supabase / Postgres<br/>system of record<br/>[client.py]")]
  node_memory_weaver["Memory Weaver<br/>knowledge sync<br/>[sync.py]"]
end

subgraph group_external["External Services"]
  node_telegram(("Telegram APIs<br/>external messaging"))
  node_anthropic(("Anthropic / Claude<br/>external LLM"))
  node_metaapi(("MetaApi &amp; Brokers<br/>external broker"))
end

node_telegram -->|"group messages"| node_listener
node_listener -->|"session and dedup"| node_listener_sessions
node_listener_sessions -->|"enqueue signals"| node_redis
node_redis -->|"consume work"| node_signal_consumer
node_signal_consumer -->|"assembled signal"| node_signal_service
node_signal_service -->|"structured trade intent"| node_risk_engine
node_risk_engine -->|"approved trade"| node_trade_service
node_trade_service -->|"execute"| node_trade_executor
node_trade_executor -->|"broker connection"| node_broker_lifecycle
node_broker_lifecycle -->|"orders and sync"| node_metaapi
node_telegram -->|"webhooks and callbacks"| node_telegram_ui
node_telegram_ui -->|"user actions"| node_api
node_api -->|"provisioning"| node_onboarding
node_api -->|"subscription checks"| node_billing
node_api -->|"commands and conversation"| node_hermes
node_hermes -->|"model requests"| node_model_router
node_model_router -->|"provider calls"| node_anthropic
node_signal_service -.->|"optional AI interpretation"| node_model_router
node_hermes -->|"contextual memory"| node_durable_memory
node_api -->|"tenant-scoped data"| node_database
node_trade_service -->|"trades and rules"| node_database
node_durable_memory -->|"persist memory"| node_database
node_database -->|"knowledge sync source"| node_memory_weaver
node_trade_service -->|"confirmation and status"| node_telegram_ui

click node_listener "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/listener/main.py"
click node_listener_sessions "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/listener/session_manager.py"
click node_signal_consumer "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/queue/signal_assembly.py"
click node_signal_service "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/signals/service.py"
click node_risk_engine "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/risk/engine.py"
click node_trade_service "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/trades/service.py"
click node_trade_executor "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/trades/executor.py"
click node_broker_lifecycle "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/brokers/pool.py"
click node_api "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/main.py"
click node_telegram_ui "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/telegram/webhook.py"
click node_onboarding "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/onboarding/dispatch.py"
click node_billing "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/billing/limits.py"
click node_hermes "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/hermes/agent_manager.py"
click node_model_router "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/hermes/model_router/router.py"
click node_durable_memory "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/hermes/memory_manager.py"
click node_database "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/db/client.py"
click node_memory_weaver "https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/memory_weaver/sync.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_listener,node_listener_sessions,node_redis toneBlue
class node_signal_consumer,node_signal_service,node_risk_engine,node_trade_service,node_trade_executor,node_broker_lifecycle,node_api,node_telegram_ui,node_onboarding,node_billing toneAmber
class node_hermes,node_model_router,node_durable_memory toneMint
class node_database,node_memory_weaver toneRose
class node_telegram,node_anthropic,node_metaapi toneIndigo
```

## Components

### Signal Ingestion

- [Telethon Listener](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/listener/main.py): Python service · Persistent Telegram group listener. · `KAIROS - the product/listener/main.py`
- [Session & Dedup](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/listener/session_manager.py): listener layer · Maintains user sessions and suppresses duplicate messages. · `KAIROS - the product/listener/session_manager.py`
- **Redis Queue**: queue · Boundary between persistent listener and backend processing.

### Backend Trade Flow

- [Signal Assembly](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/queue/signal_assembly.py): queue consumer · Consumes Redis work and assembles signal fragments. · `KAIROS - the product/backend/app/queue/signal_assembly.py`
- [Signal Interpretation](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/signals/service.py): signal domain · Parses and routes structured signals into trade handling. · `KAIROS - the product/backend/app/signals/service.py`
- [Risk Gate](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/risk/engine.py): risk engine · Hard execution boundary for sizing, limits, and halts. · `KAIROS - the product/backend/app/risk/engine.py`
- [Trade Service](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/trades/service.py): trade domain · Converges approved manual and automatic trade flows. · `KAIROS - the product/backend/app/trades/service.py`
- [Trade Executor](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/trades/executor.py): broker adapter · Submits approved trades through MetaApi. · `KAIROS - the product/backend/app/trades/executor.py`
- [Broker Lifecycle](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/brokers/pool.py): broker operations · Pools connections and handles sync, degradation, and reconciliation. · `KAIROS - the product/backend/app/brokers/pool.py`
- [FastAPI Backend](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/main.py): API service · Deployable backend and Telegram callback ingress. · `KAIROS - the product/backend/app/main.py`
- [Telegram Bot & Webhook](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/telegram/webhook.py): Telegram interface · Handles confirmations, commands, and notifications. · `KAIROS - the product/backend/app/telegram/webhook.py`
- [Onboarding](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/onboarding/dispatch.py): provisioning flow · Provisions identities, groups, brokers, and risk preferences. · `KAIROS - the product/backend/app/onboarding/dispatch.py`
- [Billing Limits](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/billing/limits.py): subscription enforcement · Meters usage and enforces subscription limits. · `KAIROS - the product/backend/app/billing/limits.py`

### Hermes Intelligence

- [Hermes Orchestrator](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/hermes/agent_manager.py): agent control plane · Routes conversation, commands, reasoning, and trading management. · `KAIROS - the product/backend/app/hermes/agent_manager.py`
- [Model Router](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/hermes/model_router/router.py): LLM policy layer · Selects providers with policy, fallback, cache, metrics, and alerts. · `KAIROS - the product/backend/app/hermes/model_router/router.py`
- [Hermes Memory](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/hermes/memory_manager.py): memory manager · Maintains durable contextual memory. · `KAIROS - the product/backend/app/hermes/memory_manager.py`

### State & Operations

- [Supabase / Postgres](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/db/client.py): system of record · Tenant-scoped durable data for users, trades, rules, billing, and memory. · `KAIROS - the product/backend/app/db/client.py`
- [Memory Weaver](https://github.com/badboydemo/kairos/blob/main/KAIROS%20-%20the%20product/backend/app/memory_weaver/sync.py): knowledge sync · Synchronizes knowledge to Git and Obsidian. · `KAIROS - the product/backend/app/memory_weaver/sync.py`

### External Services

- **Telegram APIs**: external messaging · Bot API and Telethon connectivity.
- **Anthropic / Claude**: external LLM · Optional AI signal interpretation provider.
- **MetaApi & Brokers**: external broker · Broker execution and account connectivity.

## Connections

- Telegram APIs → Telethon Listener: group messages
- Telethon Listener → Session & Dedup: session and dedup
- Session & Dedup → Redis Queue: enqueue signals
- Redis Queue → Signal Assembly: consume work
- Signal Assembly → Signal Interpretation: assembled signal
- Signal Interpretation → Risk Gate: structured trade intent
- Risk Gate → Trade Service: approved trade
- Trade Service → Trade Executor: execute
- Trade Executor → Broker Lifecycle: broker connection
- Broker Lifecycle → MetaApi & Brokers: orders and sync
- Telegram APIs → Telegram Bot & Webhook: webhooks and callbacks
- Telegram Bot & Webhook → FastAPI Backend: user actions
- FastAPI Backend → Onboarding: provisioning
- FastAPI Backend → Billing Limits: subscription checks
- FastAPI Backend → Hermes Orchestrator: commands and conversation
- Hermes Orchestrator → Model Router: model requests
- Model Router → Anthropic / Claude: provider calls
- Signal Interpretation → Model Router: optional AI interpretation
- Hermes Orchestrator → Hermes Memory: contextual memory
- FastAPI Backend → Supabase / Postgres: tenant-scoped data
- Trade Service → Supabase / Postgres: trades and rules
- Hermes Memory → Supabase / Postgres: persist memory
- Supabase / Postgres → Memory Weaver: knowledge sync source
- Trade Service → Telegram Bot & Webhook: confirmation and status