# Architecture

How data flows through asiai — from hardware sensors to your terminal, browser, and AI agents.

## Overview

```
┌──────────────────────────────────────────────────────────────────────┐
│                         Your Mac (Apple Silicon)                     │
│                                                                      │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐               │
│  │   Ollama     │   │  LM Studio  │   │   mlx-lm    │  ...engines   │
│  └──────┬───────┘   └──────┬──────┘   └──────┬──────┘               │
│         │ HTTP              │ HTTP            │ HTTP                  │
│         └──────────┬────────┴────────────────┘                       │
│                    ▼                                                  │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │                      asiai core                              │     │
│  │                                                              │     │
│  │  ┌──────────┐  ┌──────────────┐  ┌──────────────────┐      │     │
│  │  │ Engines  │  │  Collectors  │  │    Benchmark     │      │     │
│  │  │ adapters │  │  (GPU, CPU,  │  │  (warmup, runs,  │      │     │
│  │  │ (6 ABC   │  │   thermal,   │  │   median, CI95)  │      │     │
│  │  │  impls)  │  │   memory)    │  │                  │      │     │
│  │  └────┬─────┘  └──────┬───────┘  └────────┬─────────┘      │     │
│  │       │               │                    │                 │     │
│  │       └───────┬───────┴────────────────────┘                 │     │
│  │               ▼                                              │     │
│  │  ┌──────────────────────────────────┐                       │     │
│  │  │       Storage (SQLite WAL)       │                       │     │
│  │  │  metrics · models · benchmarks   │                       │     │
│  │  │  engine_status · alerts          │                       │     │
│  │  │  community_submissions           │                       │     │
│  │  └──────────────┬───────────────────┘                       │     │
│  │                 │                                            │     │
│  └─────────────────┼────────────────────────────────────────────┘     │
│                    │                                                  │
│         ┌──────────┼──────────┬─────────────┐                        │
│         ▼          ▼          ▼             ▼                         │
│  ┌───────────┐ ┌────────┐ ┌──────────┐ ┌──────────┐                │
│  │    CLI    │ │  Web   │ │   MCP    │ │Prometheus│                │
│  │  (ANSI,  │ │(htmx,  │ │ (stdio,  │ │ /metrics │                │
│  │  --json) │ │ SSE,   │ │  SSE,    │ │          │                │
│  │          │ │ charts)│ │  HTTP)   │ │          │                │
│  └───────────┘ └────────┘ └──────────┘ └──────────┘                │
│                                │                                     │
└────────────────────────────────┼─────────────────────────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
             ┌───────────┐ ┌─────────┐ ┌───────────┐
             │Claude Code│ │ Cursor  │ │ AI agents │
             │  (MCP)    │ │  (MCP)  │ │  (HTTP)   │
             └───────────┘ └─────────┘ └───────────┘
```

## Key files

| Layer | Files | Role |
|-------|-------|------|
| **Engines** | `src/asiai/engines/` | ABC `InferenceEngine` + 7 adapters (Ollama, LM Studio, mlx-lm, llama.cpp, oMLX, vllm-mlx, Exo). `OpenAICompatEngine` base class for OpenAI-compatible engines. |
| **Collectors** | `src/asiai/collectors/` | System metrics: `gpu.py` (ioreg), `system.py` (CPU, memory, thermal), `processes.py` (inference activity via lsof). |
| **Benchmark** | `src/asiai/benchmark/` | `runner.py` (warmup + N runs, median, stddev, CI95), `prompts.py` (test prompts), `card.py` (SVG card generation). |
| **Storage** | `src/asiai/storage/` | `db.py` (SQLite WAL, all CRUD), `schema.py` (tables + migrations). |
| **CLI** | `src/asiai/cli.py` | Argparse entry point, all 12 commands. |
| **Web** | `src/asiai/web/` | FastAPI + htmx + SSE + ApexCharts dashboard. Routes in `routes/`. |
| **MCP** | `src/asiai/mcp/` | FastMCP server, 11 tools + 3 resources. Transports: stdio, SSE, streamable-http. |
| **Advisor** | `src/asiai/advisor/` | Hardware-aware recommendations (model sizing, engine selection). |
| **Display** | `src/asiai/display/` | ANSI formatters (`formatters.py`), CLI renderer (`cli_renderer.py`), TUI (`tui.py`). |

## Data flow

### Monitoring (daemon mode)

```
Every 60s:
  collectors → snapshot dict → store_snapshot(db) → models table
                                                  → metrics table
  engines    → engine status → store_engine_status(db)
```

### Benchmark

```
CLI --bench → detect engines → pick model → warmup → N runs
           → compute median/stddev/CI95 → store_benchmark(db)
           → render table (ANSI or JSON)
           → optional: --share → POST to community API
           → optional: --card  → generate SVG card
```

### Web dashboard

```
Browser → FastAPI → Jinja2 template (initial render)
       → htmx SSE → /api/v1/stream → real-time updates
       → ApexCharts → /api/v1/metrics?hours=N → historical graphs
```

### MCP server

```
AI agent → stdio/SSE/HTTP → FastMCP → tool call
        → runs collector/benchmark in thread pool (asyncio.to_thread)
        → returns structured JSON
```

## Design principles

1. **Zero dependencies for core** — CLI, collectors, engines, storage use only stdlib Python. Optional extras (`[web]`, `[tui]`, `[mcp]`) add dependencies only when needed.
2. **Shared Data Layer** — The same SQLite database serves CLI, web, MCP, and Prometheus. No separate data stores.
3. **Adapter pattern** — All 7 engines implement `InferenceEngine` ABC. Adding a new engine = 1 file + register in `detect.py`.
4. **Lazy imports** — Each CLI command imports its dependencies locally, keeping startup time fast.
5. **macOS-native** — `ioreg` for GPU, `launchd` for daemons, `lsof` for inference activity. No Linux abstractions.
