# unknoun01/laplace architecture

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

- Interactive diagram: https://gitdiagram.com/unknoun01/laplace
- Repository: https://github.com/unknoun01/laplace

## Overview

Laplace is an observability and optimization product for AI agents. Its main workflow instruments agent execution in the Python SDK, sends hierarchical traces to backend ingestion, stores spans, then exposes trace exploration and cost/problem analysis through the API and web UI. From those findings, users can track remediation, configure alerts, evaluate agent changes, and manage prompt versions. The README documents these product areas; sampled source confirms SDK capture, backend setup/auth, diagnosis coverage, storage behavior, and selected UI data paths, but not every route-to-service call.

Main entry points: [`apps/backend/laplace_backend/api.py`](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/api.py) (Read and product APIs), [`apps/backend/laplace_backend/storage/base.py`](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/storage/base.py) (Span storage), [`apps/web/lib/api.ts`](https://github.com/unknoun01/laplace/blob/master/apps/web/lib/api.ts) (API client), [`apps/backend/laplace_backend/main.py`](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/main.py) (Backend app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and ingestion"]
  node_sdk["Python SDK<br/>[decorators.py]"]
  node_providers["Model integrations"]
  node_otlp["OTLP ingestion<br/>[otlp.py]"]
end

subgraph group_backend["Backend analysis"]
  node_main["Backend app<br/>[main.py]"]
  node_auth["Access control<br/>[auth.py]"]
  node_api["Read and product APIs<br/>[api.py]"]
  node_storage[("Span storage<br/>[base.py]")]
  node_sqlite[("Local SQLite<br/>[sqlite.py]")]
  node_cloudstores[("Cloud stores")]
end

subgraph group_product["Product capabilities"]
  node_insights["Waste detection<br/>[motor.py]"]
  node_coverage["Coverage analysis<br/>[coverage.py]"]
  node_alerts["Threshold alerts<br/>[alerts.py]"]
  node_panel["Cost dashboard<br/>[panel.py]"]
  node_evaluations["Evaluations<br/>[evals.py]"]
  node_prompts["Prompt versions<br/>[prompts.py]"]
end

subgraph group_interface["Web interface"]
  node_web["Web application"]
  node_home["Diagnosis screen<br/>[page.tsx]"]
  node_traceview["Trace explorer<br/>[TraceTree.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
end

node_agent(("AI agent"))
node_user(("Project user"))
node_external["Slack and webhooks"]

node_agent -->|"runs instrumented"| node_sdk
node_providers -.->|"auto-instrumented by"| node_sdk
node_sdk -->|"exports traces"| node_otlp
node_main -->|"hosts ingestion"| node_otlp
node_main -->|"hosts routes"| node_api
node_main -->|"installs middleware"| node_auth
node_otlp -->|"writes spans"| node_storage
node_storage -.->|"implemented by"| node_sqlite
node_storage -.->|"implemented by"| node_cloudstores
node_api -->|"reads traces"| node_storage
node_api -->|"requests findings"| node_insights
node_api -->|"requests coverage"| node_coverage
node_api -->|"serves alert settings"| node_alerts
node_api -->|"serves panel data"| node_panel
node_api -->|"serves evaluations"| node_evaluations
node_api -->|"serves prompt data"| node_prompts
node_insights -->|"reads usage facts"| node_storage
node_alerts -.->|"sends notifications"| node_external
node_user -->|"uses"| node_web
node_web -->|"loads data through"| node_webapi
node_webapi -->|"requests data"| node_api
node_home -->|"loads diagnosis"| node_webapi
node_traceview -->|"renders trace data"| node_webapi

click node_sdk "https://github.com/unknoun01/laplace/blob/master/packages/sdk-python/laplace/decorators.py"
click node_providers "https://github.com/unknoun01/laplace/tree/master/packages/sdk-python/laplace/integrations"
click node_otlp "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/ingest/otlp.py"
click node_main "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/main.py"
click node_auth "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/auth.py"
click node_api "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/api.py"
click node_storage "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/storage/base.py"
click node_sqlite "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/storage/sqlite.py"
click node_cloudstores "https://github.com/unknoun01/laplace/tree/master/apps/backend/laplace_backend/storage"
click node_insights "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/insights/motor.py"
click node_coverage "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/coverage.py"
click node_alerts "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/alerts.py"
click node_panel "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/panel.py"
click node_evaluations "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/evals.py"
click node_prompts "https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/prompts.py"
click node_web "https://github.com/unknoun01/laplace/tree/master/apps/web/app"
click node_home "https://github.com/unknoun01/laplace/blob/master/apps/web/app/page.tsx"
click node_traceview "https://github.com/unknoun01/laplace/blob/master/apps/web/components/TraceTree.tsx"
click node_webapi "https://github.com/unknoun01/laplace/blob/master/apps/web/lib/api.ts"

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_sdk,node_providers,node_otlp,node_user toneBlue
class node_main,node_auth,node_api,node_storage,node_sqlite,node_cloudstores toneAmber
class node_insights,node_coverage,node_alerts,node_panel,node_evaluations,node_prompts,node_external toneMint
class node_web,node_home,node_traceview,node_webapi toneRose
class node_agent toneIndigo
```

## Components

### Capture and ingestion

- [Python SDK](https://github.com/unknoun01/laplace/blob/master/packages/sdk-python/laplace/decorators.py): `packages/sdk-python/laplace/decorators.py`
- [Model integrations](https://github.com/unknoun01/laplace/tree/master/packages/sdk-python/laplace/integrations): `packages/sdk-python/laplace/integrations`
- [OTLP ingestion](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/ingest/otlp.py): `apps/backend/laplace_backend/ingest/otlp.py`

### Backend analysis

- [Backend app](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/main.py): `apps/backend/laplace_backend/main.py`
- [Access control](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/auth.py): `apps/backend/laplace_backend/auth.py`
- [Read and product APIs](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/api.py): `apps/backend/laplace_backend/api.py`
- [Span storage](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/storage/base.py): `apps/backend/laplace_backend/storage/base.py`
- [Local SQLite](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/storage/sqlite.py): `apps/backend/laplace_backend/storage/sqlite.py`
- [Cloud stores](https://github.com/unknoun01/laplace/tree/master/apps/backend/laplace_backend/storage): `apps/backend/laplace_backend/storage`

### Product capabilities

- [Waste detection](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/insights/motor.py): `apps/backend/laplace_backend/insights/motor.py`
- [Coverage analysis](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/coverage.py): `apps/backend/laplace_backend/coverage.py`
- [Threshold alerts](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/alerts.py): `apps/backend/laplace_backend/alerts.py`
- [Cost dashboard](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/panel.py): `apps/backend/laplace_backend/panel.py`
- [Evaluations](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/evals.py): `apps/backend/laplace_backend/evals.py`
- [Prompt versions](https://github.com/unknoun01/laplace/blob/master/apps/backend/laplace_backend/prompts.py): `apps/backend/laplace_backend/prompts.py`

### Web interface

- [Web application](https://github.com/unknoun01/laplace/tree/master/apps/web/app): `apps/web/app`
- [Diagnosis screen](https://github.com/unknoun01/laplace/blob/master/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Trace explorer](https://github.com/unknoun01/laplace/blob/master/apps/web/components/TraceTree.tsx): `apps/web/components/TraceTree.tsx`
- [API client](https://github.com/unknoun01/laplace/blob/master/apps/web/lib/api.ts): `apps/web/lib/api.ts`

### Other components

- **AI agent**
- **Project user**
- **Slack and webhooks**

## Connections

- AI agent → Python SDK: runs instrumented
- Model integrations → Python SDK: auto-instrumented by
- Python SDK → OTLP ingestion: exports traces
- Backend app → OTLP ingestion: hosts ingestion
- Backend app → Read and product APIs: hosts routes
- Backend app → Access control: installs middleware
- OTLP ingestion → Span storage: writes spans
- Span storage → Local SQLite: implemented by
- Span storage → Cloud stores: implemented by
- Read and product APIs → Span storage: reads traces
- Read and product APIs → Waste detection: requests findings
- Read and product APIs → Coverage analysis: requests coverage
- Read and product APIs → Threshold alerts: serves alert settings
- Read and product APIs → Cost dashboard: serves panel data
- Read and product APIs → Evaluations: serves evaluations
- Read and product APIs → Prompt versions: serves prompt data
- Waste detection → Span storage: reads usage facts
- Threshold alerts → Slack and webhooks: sends notifications
- Project user → Web application: uses
- Web application → API client: loads data through
- API client → Read and product APIs: requests data
- Diagnosis screen → API client: loads diagnosis
- Trace explorer → API client: renders trace data