Orbiter Web — System Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Browser                              │
│  ┌──────────────────────┐  ┌─────────────────────────────┐  │
│  │   Astro 5.x Pages    │  │   React Islands (Canvas)    │  │
│  │  (SSG + client JS)   │  │  (ReactFlow, client:only)   │  │
│  └──────────┬───────────┘  └──────────────┬──────────────┘  │
│             │  fetch /api/v1/*             │                 │
│             │  WebSocket /api/v1/ws        │                 │
└─────────────┼─────────────────────────────┼─────────────────┘
              │                             │
    ┌─────────▼─────────────────────────────▼─────────┐
    │              Vite Dev Proxy (:4321)              │
    │          /api/* → localhost:8000                 │
    └─────────────────────┬───────────────────────────┘
                          │
    ┌─────────────────────▼───────────────────────────┐
    │             FastAPI (uvicorn :8000)              │
    │                                                 │
    │  ┌────────────────────────────────────────────┐  │
    │  │            Middleware Stack                 │  │
    │  │  CORS → Security → Rate Limit → CSRF →     │  │
    │  │  API Version Redirect                      │  │
    │  └────────────────────────────────────────────┘  │
    │                                                 │
    │  ┌──────────────┐  ┌────────────────────────┐  │
    │  │  REST Routes  │  │  WebSocket Endpoint    │  │
    │  │  /api/v1/*    │  │  /api/v1/ws            │  │
    │  │  (45+ routers)│  │  (multiplexed channels)│  │
    │  └──────┬───────┘  └───────────┬────────────┘  │
    │         │                      │                │
    │  ┌──────▼──────────────────────▼────────────┐  │
    │  │           Service Layer                   │  │
    │  │  AgentService · Scheduler · RunQueue ·    │  │
    │  │  MemoryService · Sandbox · Evaluators ·   │  │
    │  │  DocumentProcessor · Audit · Cleanup      │  │
    │  └──────────────────┬───────────────────────┘  │
    │                     │                           │
    │  ┌──────────────────▼───────────────────────┐  │
    │  │        SQLite (WAL mode, aiosqlite)       │  │
    │  │  69 migrations · FTS5 full-text search    │  │
    │  │  Foreign keys ON · Row factory            │  │
    │  └──────────────────────────────────────────┘  │
    │                                                 │
    │  ┌──────────────────────────────────────────┐  │
    │  │         Orbiter Framework Bridge          │  │
    │  │  orbiter-core · orbiter-models            │  │
    │  │  (Agent, Tool, ModelProvider)             │  │
    │  └──────────────────────────────────────────┘  │
    └─────────────────────────────────────────────────┘
              │                     │
    ┌─────────▼───────┐   ┌────────▼──────────┐
    │  File Storage    │   │  LLM Providers    │
    │  data/uploads/   │   │  OpenAI, Anthropic│
    │  data/artifacts/ │   │  Gemini, Vertex,  │
    │                  │   │  Ollama (local)    │
    └──────────────────┘   └───────────────────┘

src/pages/
├── index.astro              # Landing / dashboard
├── login.astro              # Auth (uses BaseLayout, not PageLayout)
├── projects/                # Project management
├── agents/                  # Agent configuration & editing
├── workflows/               # Visual workflow canvas
├── playground.astro         # Agent chat playground
├── tools/                   # Tool catalog & schema editor
├── knowledge/               # Knowledge base & RAG
├── crews/                   # Multi-agent crews
├── monitoring/              # Runs, logs, costs, alerts, health
├── evaluations.astro        # Agent evaluation
├── deployments.astro        # Deployment management
├── plugins/                 # Plugin marketplace
├── settings.astro           # User settings
└── docs/                    # Embedded documentation

@asynccontextmanager
async def lifespan(app):
    _validate_startup()       # Check secret key, DB path
    await run_migrations()    # Apply pending SQL migrations
    await start_scheduler()   # Cron-based workflow scheduling
    await start_cleanup()     # Periodic session/data cleanup
    await start_mcp_health()  # MCP server health monitoring
    yield
    await stop_mcp_health()
    await stop_cleanup()
    await stop_scheduler()

erDiagram
    users ||--o{ sessions : has
    users ||--o{ projects : owns
    users ||--o{ agents : owns
    users ||--o{ providers : configures
    users ||--o{ tools : creates
    users ||--o{ knowledge_bases : owns
    users ||--o{ evaluations : runs

    projects ||--o{ applications : contains
    projects ||--o{ workflows : contains
    projects ||--o{ mcp_servers : configures

    agents ||--o{ runs : executes
    agents ||--o{ conversations : has
    agents ||--o{ agent_memory : stores
    agents ||--o{ neuron_pipelines : configures
    agents ||--o{ evaluations : tested_by
    agents ||--o{ crews : member_of

    providers ||--o{ provider_keys : has

    workflows ||--o{ workflow_runs : executes
    workflow_runs ||--o{ checkpoints : saves

    conversations ||--o{ messages : contains

    knowledge_bases ||--o{ documents : contains

    users {
        text id PK
        text email
        text password_hash
        text role
        text created_at
    }

    sessions {
        text id PK
        text user_id FK
        text csrf_token
        text expires_at
    }

    projects {
        text id PK
        text name
        text user_id FK
        text created_at
    }

    agents {
        text id PK
        text name
        text instructions
        text model_provider
        text model_name
        text tools_json
        text handoffs_json
        integer max_steps
        real temperature
        text user_id FK
        text project_id FK
    }

    providers {
        text id PK
        text name
        text provider_type
        text encrypted_api_key
        text base_url
        text load_balance_strategy
        text user_id FK
    }

    workflows {
        text id PK
        text name
        text nodes_json
        text edges_json
        text viewport_json
        text project_id FK
        text user_id FK
    }

    knowledge_bases {
        text id PK
        text name
        text search_type
        integer top_k
        real similarity_threshold
        text user_id FK
    }

001_create_users.sql
002_create_projects.sql
...
069_create_observability_integrations.sql

{
  "channel": "chat | execution | logs | sandbox | notifications | system",
  "type": "<message-type>",
  "payload": { ... }
}

Client                                Server
  │                                      │
  │─── WebSocket connect ──────────────→│
  │    (orbiter_session cookie)          │
  │                                      │ Validate session
  │                                      │ Auto-subscribe to "system"
  │←── {system, connected, user_id} ────│
  │                                      │
  │─── {type: subscribe, channel: chat}→│
  │←── {system, subscribed, chat} ──────│
  │                                      │
  │←── {system, ping} ─────────────────│ Every 30s
  │─── {type: pong} ───────────────────→│ Must reply within 10s
  │                                      │
  │←── {chat, token, {text: "..."}} ───│ Streamed responses
  │←── {chat, done, {}} ──────────────│

┌─────────────────────────────────────────────┐
│              Database (agents table)         │
│  name, instructions, model_provider,        │
│  model_name, tools_json, max_steps, ...     │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│              AgentService                     │
│                                              │
│  1. _load_agent_row(agent_id)                │
│     → SELECT * FROM agents WHERE id = ?      │
│                                              │
│  2. _resolve_provider(type, model, user_id)  │
│     → Look up provider + decrypt API key     │
│     → get_provider("openai:gpt-4o", key=...) │
│                                              │
│  3. _resolve_tools(tools_json, ...)          │
│     → Load tool schemas from tools table     │
│     → Create FunctionTool wrappers           │
│                                              │
│  4. Agent(name=..., model=..., tools=...)    │
│     → Return configured orbiter.Agent        │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│            orbiter.Agent.run()                │
│  → ModelProvider.complete() or .stream()     │
│  → Tool execution loop                       │
│  → Return ModelResponse / StreamChunk        │
└──────────────────────────────────────────────┘

1. POST /api/v1/auth/login {email, password}
   → Verify bcrypt hash
   → Create session row with UUID + CSRF token
   → Set orbiter_session HttpOnly cookie (SameSite=Lax)
   → Return UserResponse

2. Subsequent requests:
   → Cookie sent automatically
   → get_current_user() dependency validates session
   → Mutating requests require X-CSRF-Token header
     (auto-injected by PageLayout monkey-patch on window.fetch)

3. POST /api/v1/auth/logout
   → Delete session row
   → Clear cookie

1. Generate API key in Settings > API Keys
   → Key stored encrypted in api_keys table

2. Requests include X-API-Key header
   → _get_ci_user() in routes/ci.py validates
   → CSRF exempt via _EXEMPT_PREFIXES

data/
├── uploads/         # User file uploads (documents, images)
│   └── <uuid>/      # Per-upload directory
└── artifacts/       # Agent-generated artifacts
    └── <uuid>/      # Per-artifact versioned files

orbiter.db           # SQLite database (WAL mode)

routes/
├── auth.py            # Login, logout, CSRF, password management, RBAC
├── projects.py        # Project CRUD
├── agents.py          # Agent CRUD + configuration
├── workflows.py       # Workflow CRUD + canvas state
├── workflow_runs.py   # Execution engine + REST + WebSocket
├── playground.py      # Agent chat playground
├── tools.py           # Tool catalog (built-in + user-defined)
├── knowledge_bases.py # KB + document CRUD + search
├── providers.py       # LLM provider configuration
├── provider_keys.py   # API key management (encrypted)
├── conversations.py   # Chat history persistence
├── evaluations.py     # Agent evaluation
├── deployments.py     # Deployment management
├── plugins.py         # Marketplace + installed plugins
├── sandbox.py         # Code execution
├── schedules.py       # Cron scheduling
├── webhooks.py        # Webhook triggers
├── ci.py              # CI/CD API key auth
├── audit_log.py       # Audit log viewing
├── search.py          # Global FTS5 search
├── ...                # 25+ additional route modules
└── workspace_settings.py