# blazeup-ai/observal architecture

> Architecture diagram of the GitHub repository blazeup-ai/observal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blazeup-ai/observal
- Repository: https://github.com/blazeup-ai/observal

## Overview

1. **What this repo is**
   - Observal is a self-hosted platform for AI coding agents, split into three user-facing surfaces: the **registry/server**, the **desktop/IDE CLI**, and the **web UI**.
   - The architecture is intentionally “dual-plane”: a **registry plane** for agent definitions and a **telemetry/observability plane** for sessions, traces, scores, and reports.

2. **Backend server is the system hub**
   - The main backend lives in `observal-server/` and is a **Python 3.11+ FastAPI** application with **Strawberry GraphQL** layered on top.
   - Route structure is split by domain: agents, components, auth, ingest, sessions, telemetry, eval, review, insights, admin, sandbox, MCP, and more.
   - Cross-cutting middleware covers request IDs, content-type handling, rate limiting, sanitization, and SSRF/security guards.

3. **Persistent storage is split by workload**
   - **PostgreSQL** stores durable product data: users, orgs, agents, components, versions, auth config, reviews, alerts, prompts, sandboxes, and enterprise settings.
   - **ClickHouse** stores high-volume telemetry: traces, sessions, spans, token usage, dashboards, and insight/eval analytics.
   - **Redis** is used for cache, locks, and async job coordination; the repo includes `arq`-style worker processing.

4. **Telemetry ingestion pipeline**
   - The ingest boundary is exposed by backend routes and is fed by the CLI/IDE hooks and shim integrations.
   - Incoming session data is parsed by dedicated session parsers (`claude_code`, `kiro`, generic ingest classification) and then normalized into session/trace models.
   - Telemetry flows into ClickHouse for querying by dashboard, trace detail, errors, and insights pages.

5. **Registry and versioning subsystem**
   - The registry models an agent as a bundle of config: **MCP servers, skills, hooks, prompts, sandboxes, model choices, and IDE-specific metadata**.
   - Agents and components are versioned separately; the server has resolvers/builders/generators for producing installable configs and lock files.
   - A review workflow exists for submissions, drafts, and approvals, which is surfaced in admin UI and enforced in server routes/services.

6. **Analytics, eval, and insights are a separate processing layer**
   - The `services/eval/` package implements the scoring pipeline: sanitization, canary/adversarial checks, structural scoring, aggregation, and watchdog/control logic.
   - `services/insights/` plus `ee/observal_insights/` generate higher-level reports from sessions, including deduplication, facets, enrichment, narrative summaries, and HTML export.
   - The eval engine can call external LLMs, including **AWS Bedrock** or OpenAI-compatible endpoints, to score or summarize sessions.

7. **CLI is the client-side orchestration layer**
   - `observal_cli/` is a Python/Typer/Rich command-line client used for auth, pulling registry artifacts, reconciling local configs, scanning, doctor/support, sandboxing, and telemetry flushing.
   - It also installs and manages **IDE hooks, proxy/shim behavior, and session push logic**, acting as the bridge between local developer tools and the server.
   - This is the main edge boundary where agent activity is captured before it reaches the backend.

8. **IDE integrations and local capture**
   - The CLI contains IDE-specific specs and hooks for Claude Code, Kiro, and others, plus a shim/proxy path for tools that cannot emit native hooks.
   - Local capture also includes telemetry buffering and redaction so sensitive payloads can be minimized before upload.
   - This makes the CLI a control point for both **installation/config generation** and **runtime data collection**.

9. **Web app is the operator and analyst surface**
   - `web/` is a **Next.js 16 + React 19** application used for registry browsing, agent/component editing, dashboards, insights, review queues, admin pages, and trace inspection.
   - It consumes backend APIs via a typed API layer and GraphQL client; route groups separate auth, registry, user, and admin areas.
   - The frontend is mostly a presentation/query layer, not a domain engine.

10. **Enterprise extensions are isolated**
   - The `ee/` tree adds enterprise-only backend modules: SSO/SAML, SCIM, audit logging, enterprise guards, and additional insights support.
   - The separation is architectural as well as licensing-based: base OSS server routes are augmented by enterprise middleware/routes/services where available.
   - This is the main boundary for identity lifecycle and enterprise admin features.

11. **Deployment topology**
   - The repo includes a full containerized stack via **Docker Compose** and dedicated Dockerfiles for API and web.
   - Supporting infra includes **Nginx**, **Prometheus**, **Grafana dashboards**, **ClickHouse config**, and AWS **Terraform** for self-hosting on ECS/VPC/ALB/Postgres/Redis/S3.
   - There is also a one-line install/server-package path that bootstraps a prebuilt stack without cloning the repo.

12. **Operational and safety concerns are first-class**
   - Support bundles, redaction, security-event logging, payload sanitization, and SSRF protection are built into the backend/CLI flow.
   - Tests are broad and include backend API, telemetry ingestion, eval pipelines, CLI commands, enterprise auth, and end-to-end frontend flows, reflecting the system’s multiple boundaries.
   - For an architecture diagram, the key arrows are: **IDE/CLI → backend ingest → ClickHouse/Postgres → web dashboards/eval/insights**, with **enterprise identity** and **async workers** attached to the backend core.

Main entry points: [`observal-server/main.py`](https://github.com/blazeup-ai/observal/blob/main/observal-server/main.py) (API server), [`observal-server/api/routes/ingest.py`](https://github.com/blazeup-ai/observal/blob/main/observal-server/api/routes/ingest.py) (Telemetry routes), [`observal-server/services/clickhouse.py`](https://github.com/blazeup-ai/observal/blob/main/observal-server/services/clickhouse.py) (ClickHouse), [`infra/terraform/aws/README.md`](https://github.com/blazeup-ai/observal/blob/main/infra/terraform/aws/README.md) (AWS Terraform)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend core"]
  node_server_api["API server<br/>FastAPI + GraphQL<br/>[main.py]"]
  node_server_routes_registry["Registry routes<br/>HTTP routes<br/>[agent.py]"]
  node_server_routes_observability["Telemetry routes<br/>HTTP routes<br/>[ingest.py]"]
  node_server_services_registry["Registry services<br/>builders/resolvers<br/>[agent_builder.py]"]
  node_server_services_ingest["Ingest pipeline<br/>session normalizer<br/>[session_ingest.py]"]
  node_server_services_eval["Eval engine<br/>scoring pipeline<br/>[eval_engine.py]"]
  node_server_services_insights["Insights engine<br/>report generation<br/>[batch.py]"]
  node_server_storage_pg[("Postgres<br/>durable store<br/>[database.py]")]
  node_server_storage_ch[("ClickHouse<br/>analytics store<br/>[clickhouse.py]")]
  node_server_storage_redis[("Redis<br/>cache/locks<br/>[redis.py]")]
  node_server_worker["Worker<br/>async jobs<br/>[worker.py]"]
end

subgraph group_client["Clients"]
  node_cli_app["CLI client<br/>Typer/Rich CLI<br/>[main.py]"]
  node_cli_hooks["IDE hooks<br/>local capture<br/>[session_push.py]"]
  node_cli_telemetry["Telemetry buffer<br/>redaction/buffer"]
  node_web_app["Web app<br/>Next.js UI<br/>[layout.tsx]"]
  node_web_registry["Registry UI<br/>presentation layer"]
  node_web_analytics["Analytics UI<br/>presentation layer<br/>[dashboard-card.tsx]"]
end

subgraph group_enterprise["Enterprise"]
  node_ee_identity["Enterprise identity<br/>SSO/SCIM<br/>[sso_saml.py]"]
  node_ee_insights["EE insights<br/>enterprise reports<br/>[generator.py]"]
end

subgraph group_infra["Infra & deploy"]
  node_docker_stack["Docker stack<br/>compose/runtime<br/>[docker-compose.yml]"]
  node_grafana_dashboards["Grafana dashboards<br/>observability assets"]
  node_aws_terraform["AWS Terraform<br/>deployment IaC<br/>[README.md]"]
end

node_cli_hooks -->|"buffers"| node_cli_telemetry
node_cli_app -->|"installs"| node_cli_hooks
node_cli_app -->|"auth/pull"| node_server_api
node_cli_app -->|"pushes"| node_server_routes_observability
node_server_api -->|"serves"| node_server_routes_registry
node_server_api -->|"serves"| node_server_routes_observability
node_server_routes_registry -->|"uses"| node_server_services_registry
node_server_routes_registry -->|"reads/writes"| node_server_storage_pg
node_server_routes_observability -->|"normalizes"| node_server_services_ingest
node_server_routes_observability -->|"scores"| node_server_services_eval
node_server_routes_observability -->|"summarizes"| node_server_services_insights
node_server_services_ingest -->|"writes"| node_server_storage_ch
node_server_services_insights -->|"queries"| node_server_storage_ch
node_server_services_eval -->|"queries"| node_server_storage_ch
node_server_services_registry -->|"persists"| node_server_storage_pg
node_server_api -->|"uses"| node_server_storage_redis
node_server_api -->|"queues"| node_server_worker
node_server_api -->|"extends"| node_ee_identity
node_server_services_insights -->|"extends"| node_ee_insights
node_web_app -->|"consumes"| node_server_api
node_web_registry -->|"renders"| node_server_routes_registry
node_web_analytics -->|"renders"| node_server_routes_observability
node_docker_stack -->|"runs"| node_server_api
node_docker_stack -->|"runs"| node_web_app
node_docker_stack -->|"includes"| node_server_storage_ch
node_grafana_dashboards -->|"visualizes"| node_server_storage_ch
node_aws_terraform -.->|"mirrors"| node_docker_stack
node_aws_terraform -->|"provisions"| node_server_storage_pg
node_aws_terraform -->|"provisions"| node_server_storage_redis
node_aws_terraform -->|"provisions"| node_server_storage_ch

click node_server_api "https://github.com/blazeup-ai/observal/blob/main/observal-server/main.py"
click node_server_routes_registry "https://github.com/blazeup-ai/observal/blob/main/observal-server/api/routes/agent.py"
click node_server_routes_observability "https://github.com/blazeup-ai/observal/blob/main/observal-server/api/routes/ingest.py"
click node_server_services_registry "https://github.com/blazeup-ai/observal/blob/main/observal-server/services/agent_builder.py"
click node_server_services_ingest "https://github.com/blazeup-ai/observal/blob/main/observal-server/services/session_ingest.py"
click node_server_services_eval "https://github.com/blazeup-ai/observal/blob/main/observal-server/services/eval/eval_engine.py"
click node_server_services_insights "https://github.com/blazeup-ai/observal/blob/main/observal-server/services/insights/batch.py"
click node_server_storage_pg "https://github.com/blazeup-ai/observal/blob/main/observal-server/database.py"
click node_server_storage_ch "https://github.com/blazeup-ai/observal/blob/main/observal-server/services/clickhouse.py"
click node_server_storage_redis "https://github.com/blazeup-ai/observal/blob/main/observal-server/services/redis.py"
click node_server_worker "https://github.com/blazeup-ai/observal/blob/main/observal-server/worker.py"
click node_cli_app "https://github.com/blazeup-ai/observal/blob/main/observal_cli/main.py"
click node_cli_hooks "https://github.com/blazeup-ai/observal/blob/main/observal_cli/hooks/session_push.py"
click node_cli_telemetry "https://github.com/blazeup-ai/observal/blob/main/observal_cli/telemetry_buffer.py"
click node_web_app "https://github.com/blazeup-ai/observal/blob/main/web/src/app/layout.tsx"
click node_web_registry "https://github.com/blazeup-ai/observal/blob/main/web/src/components/registry/agent-edit-form.tsx"
click node_web_analytics "https://github.com/blazeup-ai/observal/blob/main/web/src/components/dashboard/dashboard-card.tsx"
click node_ee_identity "https://github.com/blazeup-ai/observal/blob/main/ee/observal_server/routes/sso_saml.py"
click node_ee_insights "https://github.com/blazeup-ai/observal/blob/main/ee/observal_insights/generator.py"
click node_docker_stack "https://github.com/blazeup-ai/observal/blob/main/docker/docker-compose.yml"
click node_grafana_dashboards "https://github.com/blazeup-ai/observal/blob/main/grafana/dashboards/session-overview.json"
click node_aws_terraform "https://github.com/blazeup-ai/observal/blob/main/infra/terraform/aws/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_api,node_server_routes_registry,node_server_routes_observability,node_server_services_registry,node_server_services_ingest,node_server_services_eval,node_server_services_insights,node_server_storage_pg,node_server_storage_ch,node_server_storage_redis,node_server_worker toneBlue
class node_cli_app,node_cli_hooks,node_cli_telemetry,node_web_app,node_web_registry,node_web_analytics toneAmber
class node_ee_identity,node_ee_insights toneMint
class node_docker_stack,node_grafana_dashboards,node_aws_terraform toneRose
```

## Components

### Backend core

Python server, data stores, and processing services.

- [API server](https://github.com/blazeup-ai/observal/blob/main/observal-server/main.py): FastAPI + GraphQL · Main backend entrypoint exposing REST routes, GraphQL, middleware, and security controls. · `observal-server/main.py`
- [Registry routes](https://github.com/blazeup-ai/observal/blob/main/observal-server/api/routes/agent.py): HTTP routes · Agent, component, skill, prompt, MCP, versioning, and review endpoints. · `observal-server/api/routes/agent.py`
- [Telemetry routes](https://github.com/blazeup-ai/observal/blob/main/observal-server/api/routes/ingest.py): HTTP routes · Ingest, sessions, telemetry, dashboards, insights, eval, and feedback endpoints. · `observal-server/api/routes/ingest.py`
- [Registry services](https://github.com/blazeup-ai/observal/blob/main/observal-server/services/agent_builder.py): builders/resolvers · Agent/component config generation, lockfiles, versioning, snapshots, and registry cache logic. · `observal-server/services/agent_builder.py`
- [Ingest pipeline](https://github.com/blazeup-ai/observal/blob/main/observal-server/services/session_ingest.py): session normalizer · Session parsing, classification, redaction, and normalization before persistence or analytics. · `observal-server/services/session_ingest.py`
- [Eval engine](https://github.com/blazeup-ai/observal/blob/main/observal-server/services/eval/eval_engine.py): scoring pipeline · Sanitization, canary/adversarial checks, structural scoring, aggregation, and watchdog control. · `observal-server/services/eval/eval_engine.py`
- [Insights engine](https://github.com/blazeup-ai/observal/blob/main/observal-server/services/insights/batch.py): report generation · Batch deduplication, enrichment, narrative synthesis, and report assembly. · `observal-server/services/insights/batch.py`
- [Postgres](https://github.com/blazeup-ai/observal/blob/main/observal-server/database.py): durable store · Durable product data for users, orgs, agents, components, reviews, prompts, sandboxes, and config. · `observal-server/database.py`
- [ClickHouse](https://github.com/blazeup-ai/observal/blob/main/observal-server/services/clickhouse.py): analytics store · High-volume telemetry and analytics store for sessions, traces, spans, token usage, and dashboards. · `observal-server/services/clickhouse.py`
- [Redis](https://github.com/blazeup-ai/observal/blob/main/observal-server/services/redis.py): cache/locks · Cache, locks, and async coordination backing background processing. · `observal-server/services/redis.py`
- [Worker](https://github.com/blazeup-ai/observal/blob/main/observal-server/worker.py): async jobs · Background job runner for queued processing and delayed maintenance tasks. · `observal-server/worker.py`

### Clients

CLI capture layer and web operator surface.

- [CLI client](https://github.com/blazeup-ai/observal/blob/main/observal_cli/main.py): Typer/Rich CLI · Local control plane for auth, pull, reconcile, scan, sandbox, support, and telemetry flush. · `observal_cli/main.py`
- [IDE hooks](https://github.com/blazeup-ai/observal/blob/main/observal_cli/hooks/session_push.py): local capture · IDE-specific hooks, session push logic, and shim/proxy behavior for local capture. · `observal_cli/hooks/session_push.py`
- [Telemetry buffer](https://github.com/blazeup-ai/observal/blob/main/observal_cli/telemetry_buffer.py): redaction/buffer · Local buffering, redaction, and upload staging before telemetry reaches the backend. · `observal_cli/telemetry_buffer.py`
- [Web app](https://github.com/blazeup-ai/observal/blob/main/web/src/app/layout.tsx): Next.js UI · Operator-facing frontend for registry browsing, editing, dashboards, traces, review, and admin workflows. · `web/src/app/layout.tsx`
- [Registry UI](https://github.com/blazeup-ai/observal/blob/main/web/src/components/registry/agent-edit-form.tsx): presentation layer · Agent and component browsing, editing, install dialogs, pull commands, and submission/review interactions. · `web/src/components/registry/agent-edit-form.tsx`
- [Analytics UI](https://github.com/blazeup-ai/observal/blob/main/web/src/components/dashboard/dashboard-card.tsx): presentation layer · Dashboards, traces, insights, eval views, and admin reporting surfaces. · `web/src/components/dashboard/dashboard-card.tsx`

### Enterprise

Enterprise-only extensions for identity and analytics.

- [Enterprise identity](https://github.com/blazeup-ai/observal/blob/main/ee/observal_server/routes/sso_saml.py): SSO/SCIM · Enterprise-only SSO, SAML, SCIM, audit logging, and guard middleware layered onto the base server. · `ee/observal_server/routes/sso_saml.py`
- [EE insights](https://github.com/blazeup-ai/observal/blob/main/ee/observal_insights/generator.py): enterprise reports · Enterprise extensions for anonymization, enrichment, cross-user analysis, and HTML exports. · `ee/observal_insights/generator.py`

### Infra & deploy

Containerization, observability, and AWS deployment assets.

- [Docker stack](https://github.com/blazeup-ai/observal/blob/main/docker/docker-compose.yml): compose/runtime · Containerized API, web, Nginx, ClickHouse, and supporting service definitions for self-hosting. · `docker/docker-compose.yml`
- [Grafana dashboards](https://github.com/blazeup-ai/observal/blob/main/grafana/dashboards/session-overview.json): observability assets · Prebuilt dashboards and datasource provisioning for operational and product telemetry. · `grafana/dashboards/session-overview.json`
- [AWS Terraform](https://github.com/blazeup-ai/observal/blob/main/infra/terraform/aws/README.md): deployment IaC · Terraform modules for ECS, ALB, VPC, Postgres, Redis, ClickHouse, S3, DNS, and secrets. · `infra/terraform/aws/README.md`

## Connections

- IDE hooks → Telemetry buffer: buffers · Local capture is redacted and staged before upload.
- CLI client → IDE hooks: installs · CLI manages IDE hooks and shim/proxy capture paths.
- CLI client → API server: auth/pull · CLI talks to the backend for login, registry sync, and control operations.
- CLI client → Telemetry routes: pushes · CLI flushes session telemetry and support bundles into ingest endpoints.
- API server → Registry routes: serves · Backend exposes registry and versioning APIs.
- API server → Telemetry routes: serves · Backend exposes ingest, session, telemetry, insights, and eval APIs.
- Registry routes → Registry services: uses · Registry endpoints rely on builders, resolvers, and lockfile generators.
- Registry routes → Postgres: reads/writes · Durable registry data is persisted in Postgres.
- Telemetry routes → Ingest pipeline: normalizes · Incoming telemetry is parsed and converted to internal session models.
- Telemetry routes → Eval engine: scores · Evaluation endpoints feed scoring and aggregation pipelines.
- Telemetry routes → Insights engine: summarizes · Insights endpoints drive report generation and enrichment.
- Ingest pipeline → ClickHouse: writes · Normalized telemetry is stored for analytics and traces.
- Insights engine → ClickHouse: queries · Insights are derived from telemetry and session data in ClickHouse.
- Eval engine → ClickHouse: queries · Eval scoring reads telemetry and session artifacts from ClickHouse.
- Registry services → Postgres: persists · Registry state, versions, and submissions live in Postgres.
- API server → Redis: uses · API uses Redis for cache, locks, and coordination.
- API server → Worker: queues · Backend hands off async jobs to worker processing.
- API server → Enterprise identity: extends · Enterprise routes and guards augment the base server.
- Insights engine → EE insights: extends · Enterprise insights adds anonymization, cross-user analysis, and exports.
- Web app → API server: consumes · Frontend queries backend APIs and GraphQL for data and mutations.
- Registry UI → Registry routes: renders · Registry UI is driven by registry and versioning endpoints.
- Analytics UI → Telemetry routes: renders · Analytics UI is driven by telemetry, dashboards, insights, and eval endpoints.
- Docker stack → API server: runs · Compose stack deploys the backend service.
- Docker stack → Web app: runs · Compose stack deploys the web application.
- Docker stack → ClickHouse: includes · Stack includes ClickHouse for telemetry analytics.
- Grafana dashboards → ClickHouse: visualizes · Dashboards read analytics data from ClickHouse.
- AWS Terraform → Docker stack: mirrors · Terraform models the same self-hosted topology in AWS.
- AWS Terraform → Postgres: provisions · Infra defines managed Postgres for durable data.
- AWS Terraform → Redis: provisions · Infra defines Redis for cache and coordination.
- AWS Terraform → ClickHouse: provisions · Infra defines ClickHouse for telemetry analytics.
