# quantiota/ai-agent-host architecture

> Architecture diagram of the GitHub repository quantiota/ai-agent-host, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quantiota/ai-agent-host
- Repository: https://github.com/quantiota/ai-agent-host

## Overview

##### Project Type and Purpose
- This is a containerized “AI Agent Host” platform built with Docker Compose.
- It provides an agentic, data-aware environment for LangChain applications by combining:
- QuestDB (time-series database)
- Grafana (visualization)
- Code-Server (web IDE)
- Nginx (reverse proxy / routing)
- It also includes a sample AI agent (“Claude Code”) that runs as a separate service inside the same Docker network and uses system-level tools (curl, database clients, file I/O) to orchestrate tasks.

##### File Structure Analysis
- Top-level:
- .github, LICENSE, README.md
- claude-code/…: agent service code and scripts for batch & real-time logging, parsers, Docker config
- docker/: core Docker Compose config and per-service folders
- notebooks/: example market-data processing notebooks
- ska-framework/: reference papers
- tests/: placeholder for test suites
- docker/ subdirectories:
- grafana/: dashboards + provisioning
- nginx/: TLS certs, routing configs, htpasswd
- vscode/: Dockerfile & requirements for Code-Server
- docker-compose.yaml & .env: defines all services & their interconnections

##### Key README Insights
- The stack is designed to spin up seamlessly via docker compose.
- Services talk over the internal Docker network.
- Claude Code is added without touching the core stack—illustrating an extensible architecture.

##### Main Components & Interactions (
a. Components:
- Nginx (reverse proxy, TLS termination)
- Code-Server container (VS Code IDE)
- QuestDB container (time-series DB)
- Grafana container (dashboards)
- Claude Code service (agent container)
- Optional: remote JupyterHub (external service)
- User’s browser / client
b. Relationships:
- User ↔️ Nginx (HTTPS entrypoint)
- Nginx ↔️ Code-Server, Grafana, QuestDB (routing by hostname/path)
- Code-Server ↔️ remote JupyterHub (via Jupyter HTTP API)
- Claude Code ↔️ Code-Server, QuestDB, Grafana (internal HTTP & DB clients)
- Grafana ↔️ QuestDB (datasource connection)
c. Architectural Patterns:
- Microservices (one container per service)
- Reverse proxy for routing and security (Nginx)
- Data-infrastructure + visualization separated from compute/UI
- Agentic extension via sidecar-style service (Claude Code)
d. Technologies:
- Docker & Docker Compose
- Nginx
- Code-Server (VS Code in container)
- QuestDB (Postgres-compatible time-series DB)
- Grafana
- Python scripts for parsing & ingestion
- LangChain (framework in user code)

##### Detailed Capture of Architectural Elements
- Persistent volumes/mounts for logs and config (e.g., Grafana dashboards, QuestDB data).
- Environment variables (.env) driving service config.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External services
    subgraph "Public Internet"
        User["User Browser"]:::external
        JupyterHub["JupyterHub (HTTP API)"]:::external
    end

    %% Docker Host containing all containers
    subgraph "Docker Host"
        direction TB
        Nginx["Nginx (443)"]:::frontend
        CodeServer["Code-Server (8080)"]:::frontend
        Grafana["Grafana (3000)"]:::frontend
        QuestDB["QuestDB (8812)"]:::datastore
        ClaudeCode["Claude Code Service"]:::agent
    end

    %% Connections
    User -->|"HTTPS"| Nginx
    Nginx -->|"proxy to Code-Server"| CodeServer
    Nginx -->|"proxy to Grafana"| Grafana
    Nginx -->|"proxy to QuestDB"| QuestDB
    CodeServer -->|"calls API"| JupyterHub
    ClaudeCode -->|"writes logs"| QuestDB
    ClaudeCode -->|"queries dashboards"| Grafana
    ClaudeCode -->|"orchestrates via IDE"| CodeServer
    Grafana -->|"reads data"| QuestDB

    %% Click Events
    click Nginx "https://github.com/quantiota/ai-agent-host/tree/main/docker/nginx/"
    click CodeServer "https://github.com/quantiota/ai-agent-host/tree/main/docker/vscode/"
    click QuestDB "https://github.com/quantiota/ai-agent-host/blob/main/docker/docker-compose.yaml"
    click Grafana "https://github.com/quantiota/ai-agent-host/tree/main/docker/grafana/"
    click ClaudeCode "https://github.com/quantiota/ai-agent-host/tree/main/claude-code/"

    %% Styling
    classDef frontend fill:#bbdefb,stroke:#0d47a1;
    classDef datastore fill:#c8e6c9,stroke:#1b5e20;
    classDef agent fill:#e1bee7,stroke:#4a148c;
    classDef external fill:#eeeeee,stroke:#757575,stroke-dasharray: 5 5;
```
