# axis-oz/nanobot-railway-template architecture

> Architecture diagram of the GitHub repository axis-oz/nanobot-railway-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/axis-oz/nanobot-railway-template
- Repository: https://github.com/axis-oz/nanobot-railway-template

## Overview

This repo is a **Railway deploy template** that packages:
- a **Python web admin panel** (Starlette + uvicorn) providing a **config UI + status dashboard + gateway control**
- a **managed nanobot “gateway” process** that runs as an **async subprocess** inside the same container
- **persistent storage** via a Railway volume mounted at **`/data`** for config/data durability across restarts

So the architecture is essentially **one container = one web server + one child gateway process**, with external integrations to LLM providers and messaging channels.

##### What the file tree tells you to include (key components)
From the tree:
- `templates/index.html` → **single web UI** served by the Python server (browser-based admin).
- `Dockerfile`, `start.sh`, `requirements.txt` → **packaging/runtime** and entrypoint (deployment node).
- `railway.toml` → Railway-specific deployment configuration (service wiring, healthcheck expectations, etc.).

This is *not* a multi-service microservice architecture; it’s a **single-service runtime with multiple internal modules and multiple external dependencies**.

##### Python Web Server (Starlette + uvicorn)
- Serves **`/`** (UI), **`/health`** (unauth), and **`/api/*`** (auth).
- Implements **Basic Auth** for admin routes.
- Reads/writes config to persistent storage (`/data`).
- Manages the gateway lifecycle (start/stop/restart).
- Captures gateway stdout/stderr into a **ring buffer** for log viewing.

##### nanobot gateway (child process / async subprocess)
- Started/stopped by the web server.
- Uses configured providers/channels to operate.
- Emits logs to stdout/stderr (captured by the web server).
- Reads config/data (likely from `/data` and/or env vars).

##### Persistent Volume mounted at `/data`
- Stores config/data
- Used by the web server (and likely the gateway)

##### External actors and systems

- **Admin user (Browser)**
- Connects to `GET /` (UI) and `GET/PUT /api/*` endpoints
- Protected by **Basic Auth** (username/password via env)

- **Railway routing / public URL**
- Routes HTTP traffic to the container on `$PORT`
- Optionally: show “public endpoint removed after setup” as an operational note (not a runtime dependency)

- **LLM Provider APIs** (Anthropic/OpenAI/OpenRouter/DeepSeek/Groq/Gemini/Zhipu/vLLM)
- Outbound calls from the gateway (and/or nanobot core)

- **Messaging Channels**
- Telegram
- WhatsApp (via bridge)
- Feishu/Lark

##### Browser ↔ Web Server
- **HTTPS/HTTP** to:
- `/` (HTML UI from `templates/index.html`)
- `/api/config` (GET masked, PUT save)
- `/api/status` (gateway/provider/channel status)
- `/api/logs` (ring buffer lines)
- `/api/gateway/*` (control plane)
- A small “Basic Auth” annotation on these routes.
- `/health` separately as **no-auth** for platform checks.

##### Web Server → Persistent Volume (`/data`)
- Read/write config
- Possibly store generated admin password info (at least logs it)

##### Web Server ↔ Gateway Subprocess
- Web server issues lifecycle commands: **start/stop/restart**
- Gateway emits:

##### Gateway ↔ External Providers/Channels
- Gateway → Provider APIs (LLM inference requests)
- Gateway ↔ Messaging platforms (send/receive messages/events)

- **Single-container, multi-process pattern**: web control-plane + managed worker (gateway) as child process.
- **Control plane vs data plane**:
- Control plane: Web UI/API + auth + config management + process control
- Data plane: Gateway operations (channels/providers)
- **Persistent state via mounted volume** (`/data`) rather than an external DB.
- **Observability via log ring buffer**: gateway logs are captured and served to UI.

Labels on components:
- **Python + Starlette + uvicorn** (Web server)
- **Docker** (Dockerfile)
- **Railway** (deployment target, volume, env vars)
- **Basic Auth** (ADMIN_USERNAME/ADMIN_PASSWORD)
- **nanobot gateway** (subprocess)
- **Persistent Volume `/data`**
- **HTML template** (`templates/index.html`)

A small “Config sources” note:
- Primary: Web UI saved config
- Secondary: env vars with `NANOBOT_` prefix (as fallback/override if relevant)

##### What *not* to overcomplicate
- Don’t invent extra services (no separate DB, no separate queue) unless you verify in code.
- Keep “Railway” as the hosting boundary rather than drawing Kubernetes-level primitives (unless you’re specifically documenting deployment internals).

- [ ] Admin Browser → Web Server endpoints (`/`, `/api/*`, `/health`)
- [ ] Basic Auth boundary on admin endpoints (not on `/health`)
- [ ] Web Server ↔ Gateway lifecycle control (start/stop/restart)
- [ ] Gateway logs → Web Server ring buffer → UI `/api/logs`
- [ ] Persistent volume `/data` used for config/data
- [ ] Gateway ↔ External Providers and Channels
- [ ] Railway env vars (PORT, ADMIN_USERNAME, ADMIN_PASSWORD, NANOBOT_*)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1: Deployment / Context
  %% =========================
  subgraph D1["Diagram 1: High-level Deployment / Context"]
    direction TB

    Admin["Admin User (Browser)"]:::actor
    RR["Railway Routing / Public URL\n(routes to $PORT)"]:::platform

    subgraph RSC["Railway Service / Container (Docker)"]
      direction TB

      WS["Web Admin/API (Python + Starlette + uvicorn)\nServes UI + Health + Admin API"]:::control
      GW["nanobot gateway (child process)\n(async subprocess)"]:::dataplane
      VOL[("Persistent Volume\nmounted at /data")]:::storage

      WS -->|"read/write config&data"| VOL
      WS -->|"start/stop/restart"| GW
      GW -->|"stdout/stderr logs"| WS
      GW -->|"read config/data"| VOL
    end

    subgraph EXT["External Integrations"]
      direction TB

      subgraph LLM["LLM Provider APIs (examples)"]
        direction TB
        Providers["Anthropic/OpenAI/OpenRouter/DeepSeek/Groq/\nGemini/Zhipu/vLLM"]:::external
      end

      subgraph CH["Messaging Channels"]
        direction TB
        TG["Telegram"]:::external
        WA["WhatsApp (via bridge)"]:::external
        FL["Feishu/Lark"]:::external
      end
    end

    Admin -->|"HTTPS GET / (UI)"| RR
    Admin -->|"HTTPS GET/PUT /api/* (BasicAuth)"| RR
    Admin -->|"HTTPS GET /health (no-auth)"| RR

    RR -->|"HTTP to $PORT"| WS

    GW -->|"LLM request"| Providers
    GW <-->|"Channel API (poll/webhook)"| TG
    GW <-->|"Channel API (poll/webhook)"| WA
    GW <-->|"Channel API (poll/webhook)"| FL

    ENV["Railway Env Vars\nPORT\nADMIN_USERNAME/ADMIN_PASSWORD\nNANOBOT_*"]:::note
    ENV -.->|"configure"| WS
    ENV -.->|"configure"| GW
  end

  %% =========================
  %% Diagram 2: Container internals (detailed)
  %% =========================
  subgraph D2["Diagram 2: Container Internal Components (Detailed)"]
    direction TB

    subgraph RSC2["Railway Service / Container (Docker)"]
      direction TB

      subgraph WS2["Python Web Server (Starlette + uvicorn)"]
        direction TB

        Router["Router / Endpoints"]:::control
        UI["GET / (serves admin UI HTML)"]:::control
        H["GET /health (no-auth)"]:::health
        API["/api/* (admin)"]:::control

        Auth["Auth Middleware\nBasic Auth (ADMIN_USERNAME/ADMIN_PASSWORD)"]:::security

        subgraph APIS["Admin API Endpoints"]
          direction TB
          CFG["/api/config\nGET masked • PUT save"]:::api
          ST["/api/status\n(gateway/provider/channel status)"]:::api
          LOGS["/api/logs\n(ring buffer lines)"]:::api
          GCTL["/api/gateway/*\n(control plane)"]:::api
        end

        CfgMgr["Config Manager\n(read/write /data)"]:::control
        Sup["Gateway Supervisor\n(async subprocess)"]:::control
        Ring["Log Capture\n(stdout/stderr ring buffer)"]:::observability
      end

      GW2["nanobot gateway (child process)"]:::dataplane
      VOL2[("Persistent Volume at /data")]:::storage
    end

    %% Internal wiring
    Router -->|"routes"| UI
    Router -->|"routes"| H
    Router -->|"routes"| API

    API -->|"enforce"| Auth
    Auth -->|"protects"| CFG
    Auth -->|"protects"| ST
    Auth -->|"protects"| LOGS
    Auth -->|"protects"| GCTL

    CFG -->|"persist config"| CfgMgr
    CfgMgr -->|"read/write"| VOL2

    GCTL -->|"start/stop/restart"| Sup
    Sup -->|"spawn/kill"| GW2

    GW2 -->|"stdout/stderr"| Ring
    Ring -->|"serve logs"| LOGS

    GW2 -->|"read config/data"| VOL2
  end

  %% =========================
  %% DevOps / Packaging lane
  %% =========================
  subgraph OPS["DevOps / Packaging (non-runtime request flow)"]
    direction TB

    DF["Dockerfile\n(container build)"]:::ops
    REQ["requirements.txt\n(Python dependencies)"]:::ops
    SS["start.sh\n(runtime entrypoint)"]:::ops
    RTOML["railway.toml\n(deploy config, healthcheck, env, volume mount)"]:::ops
    CI["GitHub Actions\nTelegram notify workflow"]:::ops

    DF -->|"installs"| REQ
    DF -->|"sets entrypoint"| SS
    RTOML -.->|"defines deploy/volume"| RSC
    CI -.->|"notifies"| TG
  end

  %% =========================
  %% Click events (component mapping)
  %% =========================
  click RSC "https://github.com/axis-oz/nanobot-railway-template/tree/main/Dockerfile"
  click DF "https://github.com/axis-oz/nanobot-railway-template/tree/main/Dockerfile"
  click SS "https://github.com/axis-oz/nanobot-railway-template/blob/main/start.sh"
  click WS "https://github.com/axis-oz/nanobot-railway-template/blob/main/server.py"
  click WS2 "https://github.com/axis-oz/nanobot-railway-template/blob/main/server.py"
  click Auth "https://github.com/axis-oz/nanobot-railway-template/blob/main/server.py"
  click Router "https://github.com/axis-oz/nanobot-railway-template/blob/main/server.py"
  click Sup "https://github.com/axis-oz/nanobot-railway-template/blob/main/server.py"
  click Ring "https://github.com/axis-oz/nanobot-railway-template/blob/main/server.py"
  click UI "https://github.com/axis-oz/nanobot-railway-template/blob/main/templates/index.html"
  click REQ "https://github.com/axis-oz/nanobot-railway-template/blob/main/requirements.txt"
  click RTOML "https://github.com/axis-oz/nanobot-railway-template/blob/main/railway.toml"
  click CI "https://github.com/axis-oz/nanobot-railway-template/blob/main/.github/workflows/telegram-notify.yml"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
  classDef platform fill:#E8F5E9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20
  classDef control fill:#FFF3E0,stroke:#EF6C00,stroke-width:1.5px,color:#E65100
  classDef dataplane fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1.5px,color:#4A148C
  classDef storage fill:#E0F7FA,stroke:#00838F,stroke-width:1.5px,color:#006064
  classDef external fill:#FCE4EC,stroke:#AD1457,stroke-width:1.5px,color:#880E4F
  classDef security fill:#FFEBEE,stroke:#C62828,stroke-width:1.5px,color:#B71C1C
  classDef api fill:#FFF8E1,stroke:#F9A825,stroke-width:1.5px,color:#7C6F00
  classDef health fill:#E8EAF6,stroke:#3949AB,stroke-width:1.5px,color:#1A237E
  classDef observability fill:#E0F2F1,stroke:#00796B,stroke-width:1.5px,color:#004D40
  classDef note fill:#FFFFFF,stroke:#757575,stroke-width:1px,stroke-dasharray:4 3,color:#424242
  classDef ops fill:#ECEFF1,stroke:#546E7A,stroke-width:1.5px,color:#263238
```
