docs/ARCHITECTURE.md

# Architecture

## Overview

`autonomy-labs` is a single-container FastAPI app intended to run on Hugging Face Spaces (Docker). It serves:
- static pages (`static/index.html`, `static/dashboard.html`)
- REST APIs for chat + Codex + MCP
- a WebSocket PTY-backed terminal (`/ws/terminal`)

## Backend layout

- `main.py`: minimal entrypoint (loads dotenv, creates app).
- `app/server.py`: app factory + lifespan lifecycle.
- `app/routes/*`: feature routers:
  - `base.py`: `/`, `/health`, `/config`
  - `chat.py`: `/api/chat`, `/api/proxy/models`
  - `codex.py`: `/api/codex*` and Codex login helpers
  - `mcp.py`: `/api/mcp/*`
  - `terminal.py`: `/ws/terminal`
  - `user.py`: `/api/me` and per-user persisted config (e.g., MCP registry)
- `app/auth.py`: Supabase access-token verification (server-side) with small TTL cache.
- `app/storage.py`: per-user server-side persistence directory selection (`/data` preferred).

## Frontend layout

Currently the UI is primarily `static/dashboard.html` with inline JS/CSS and CDN dependencies (Tailwind, xterm, etc).

## Execution safety model

The following capabilities are high-risk and gated:
- web terminal
- Codex execution endpoints
- MCP tool calls

Auth is enforced server-side via Supabase access tokens. Feature flags can disable them entirely.