# ataraxiavibin/the-bunker architecture

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

- Interactive diagram: https://gitdiagram.com/ataraxiavibin/the-bunker
- Repository: https://github.com/ataraxiavibin/the-bunker

## Overview

Bunker is a personal automation hub. Its main workflow runs from Telegram commands through intent registration and a routed call, to a host-side agent that executes a service and returns a normalized result. A separate CLI path reports execution events, while health checks and the two initial services provide additional product capabilities. The agent excerpt is partial, so links are limited to the documented and visible call paths.

Main entry points: [`agent.py`](https://github.com/ataraxiavibin/the-bunker/blob/main/agent.py) (Agent API and CLI), [`bunker.py`](https://github.com/ataraxiavibin/the-bunker/blob/main/bunker.py) (Orchestrator API), [`bot/bot.py`](https://github.com/ataraxiavibin/the-bunker/blob/main/bot/bot.py) (Bot handlers), [`shared/transmitter.py`](https://github.com/ataraxiavibin/the-bunker/blob/main/shared/transmitter.py) (HTTP transmitter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Telegram UI"]
  node_bot["Bot handlers<br/>[bot.py]"]
  node_tui["TUI formatting<br/>[tui.py]"]
  node_health["Health checks<br/>[connection.py]"]
  node_transmitter["HTTP transmitter<br/>[transmitter.py]"]
end

subgraph group_hub["Bunker Hub"]
  node_bunker["Orchestrator API<br/>[bunker.py]"]
  node_auth["Token verification<br/>[auth.py]"]
  node_contracts["Message contracts<br/>[models.py]"]
  node_normalizer["Reply processing<br/>[bunker.py]"]
end

subgraph group_runner["Agent Runner"]
  node_agent["Agent API and CLI<br/>[agent.py]"]
  node_service_map["Service dispatch map<br/>[agent.py]"]
  node_execution["Subprocess execution<br/>[agent.py]"]
  node_parser["Service argument parser<br/>[parser.py]"]
  node_event_report["CLI event reporting<br/>[agent.py]"]
end

subgraph group_services["Services"]
  node_berserk["Chapter checker<br/>[checker.py]"]
  node_chapter_cache[("Chapter cache<br/>[checker.py]")]
  node_pods["Bluetooth controls<br/>[connect.py]"]
end

node_telegram_user(("Telegram user"))
node_telegram(("Telegram"))
node_mangadex["MangaDex API"]
node_bluetoothctl["bluetoothctl"]

node_telegram_user -->|"sends commands"| node_telegram
node_telegram -->|"delivers updates"| node_bot
node_bot -->|"formats responses"| node_tui
node_bot -->|"checks failures"| node_health
node_health -->|"pings"| node_bunker
node_health -->|"pings"| node_agent
node_bot -->|"registers intent"| node_transmitter
node_bot -->|"sends call"| node_transmitter
node_transmitter -->|"HTTP requests"| node_bunker
node_bunker -->|"verifies token"| node_auth
node_agent -->|"verifies token"| node_auth
node_bot -->|"builds messages"| node_contracts
node_bunker -->|"validates messages"| node_contracts
node_agent -->|"uses contracts"| node_contracts
node_bunker -->|"forwards call"| node_agent
node_agent -->|"resolves target"| node_service_map
node_agent -->|"launches service"| node_execution
node_execution -->|"runs action"| node_berserk
node_execution -->|"runs action"| node_pods
node_berserk -->|"parses arguments"| node_parser
node_pods -->|"parses arguments"| node_parser
node_berserk -->|"fetches chapters"| node_mangadex
node_berserk -->|"reads and writes"| node_chapter_cache
node_pods -->|"runs commands"| node_bluetoothctl
node_agent -->|"returns reply"| node_normalizer
node_normalizer -->|"processes reply"| node_bunker
node_bunker -->|"returns result"| node_transmitter
node_agent -->|"reports CLI result"| node_event_report
node_event_report -->|"sends event"| node_transmitter
node_transmitter -->|"posts event"| node_bunker

click node_bot "https://github.com/ataraxiavibin/the-bunker/blob/main/bot/bot.py"
click node_tui "https://github.com/ataraxiavibin/the-bunker/blob/main/bot/tui.py"
click node_health "https://github.com/ataraxiavibin/the-bunker/blob/main/shared/connection.py"
click node_transmitter "https://github.com/ataraxiavibin/the-bunker/blob/main/shared/transmitter.py"
click node_bunker "https://github.com/ataraxiavibin/the-bunker/blob/main/bunker.py"
click node_auth "https://github.com/ataraxiavibin/the-bunker/blob/main/shared/auth.py"
click node_contracts "https://github.com/ataraxiavibin/the-bunker/blob/main/shared/models.py"
click node_normalizer "https://github.com/ataraxiavibin/the-bunker/blob/main/bunker.py"
click node_agent "https://github.com/ataraxiavibin/the-bunker/blob/main/agent.py"
click node_service_map "https://github.com/ataraxiavibin/the-bunker/blob/main/agent.py"
click node_execution "https://github.com/ataraxiavibin/the-bunker/blob/main/agent.py"
click node_parser "https://github.com/ataraxiavibin/the-bunker/blob/main/shared/parser.py"
click node_berserk "https://github.com/ataraxiavibin/the-bunker/blob/main/services/berserk_checker/checker.py"
click node_chapter_cache "https://github.com/ataraxiavibin/the-bunker/blob/main/services/berserk_checker/checker.py"
click node_pods "https://github.com/ataraxiavibin/the-bunker/blob/main/services/pods_connect/connect.py"
click node_event_report "https://github.com/ataraxiavibin/the-bunker/blob/main/agent.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_bot,node_tui,node_health,node_transmitter,node_telegram_user toneBlue
class node_bunker,node_auth,node_contracts,node_normalizer toneAmber
class node_agent,node_service_map,node_execution,node_parser,node_event_report,node_mangadex toneMint
class node_berserk,node_chapter_cache,node_pods toneRose
class node_telegram,node_bluetoothctl toneIndigo
```

## Components

### Telegram UI

- [Bot handlers](https://github.com/ataraxiavibin/the-bunker/blob/main/bot/bot.py): `bot/bot.py`
- [TUI formatting](https://github.com/ataraxiavibin/the-bunker/blob/main/bot/tui.py): `bot/tui.py`
- [Health checks](https://github.com/ataraxiavibin/the-bunker/blob/main/shared/connection.py): `shared/connection.py`
- [HTTP transmitter](https://github.com/ataraxiavibin/the-bunker/blob/main/shared/transmitter.py): `shared/transmitter.py`

### Bunker Hub

- [Orchestrator API](https://github.com/ataraxiavibin/the-bunker/blob/main/bunker.py): `bunker.py`
- [Token verification](https://github.com/ataraxiavibin/the-bunker/blob/main/shared/auth.py): `shared/auth.py`
- [Message contracts](https://github.com/ataraxiavibin/the-bunker/blob/main/shared/models.py): `shared/models.py`
- [Reply processing](https://github.com/ataraxiavibin/the-bunker/blob/main/bunker.py): `bunker.py`

### Agent Runner

- [Agent API and CLI](https://github.com/ataraxiavibin/the-bunker/blob/main/agent.py): `agent.py`
- [Service dispatch map](https://github.com/ataraxiavibin/the-bunker/blob/main/agent.py): `agent.py`
- [Subprocess execution](https://github.com/ataraxiavibin/the-bunker/blob/main/agent.py): `agent.py`
- [Service argument parser](https://github.com/ataraxiavibin/the-bunker/blob/main/shared/parser.py): `shared/parser.py`
- [CLI event reporting](https://github.com/ataraxiavibin/the-bunker/blob/main/agent.py): `agent.py`

### Services

- [Chapter checker](https://github.com/ataraxiavibin/the-bunker/blob/main/services/berserk_checker/checker.py): `services/berserk_checker/checker.py`
- [Chapter cache](https://github.com/ataraxiavibin/the-bunker/blob/main/services/berserk_checker/checker.py): `services/berserk_checker/checker.py`
- [Bluetooth controls](https://github.com/ataraxiavibin/the-bunker/blob/main/services/pods_connect/connect.py): `services/pods_connect/connect.py`

### Other components

- **Telegram user**
- **Telegram**
- **MangaDex API**
- **bluetoothctl**

## Connections

- Telegram user → Telegram: sends commands
- Telegram → Bot handlers: delivers updates
- Bot handlers → TUI formatting: formats responses
- Bot handlers → Health checks: checks failures
- Health checks → Orchestrator API: pings
- Health checks → Agent API and CLI: pings
- Bot handlers → HTTP transmitter: registers intent
- Bot handlers → HTTP transmitter: sends call
- HTTP transmitter → Orchestrator API: HTTP requests
- Orchestrator API → Token verification: verifies token
- Agent API and CLI → Token verification: verifies token
- Bot handlers → Message contracts: builds messages
- Orchestrator API → Message contracts: validates messages
- Agent API and CLI → Message contracts: uses contracts
- Orchestrator API → Agent API and CLI: forwards call
- Agent API and CLI → Service dispatch map: resolves target
- Agent API and CLI → Subprocess execution: launches service
- Subprocess execution → Chapter checker: runs action
- Subprocess execution → Bluetooth controls: runs action
- Chapter checker → Service argument parser: parses arguments
- Bluetooth controls → Service argument parser: parses arguments
- Chapter checker → MangaDex API: fetches chapters
- Chapter checker → Chapter cache: reads and writes
- Bluetooth controls → bluetoothctl: runs commands
- Agent API and CLI → Reply processing: returns reply
- Reply processing → Orchestrator API: processes reply
- Orchestrator API → HTTP transmitter: returns result
- Agent API and CLI → CLI event reporting: reports CLI result
- CLI event reporting → HTTP transmitter: sends event
- HTTP transmitter → Orchestrator API: posts event