# webwiebe/bugbarn architecture

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

- Interactive diagram: https://gitdiagram.com/webwiebe/bugbarn
- Repository: https://github.com/webwiebe/bugbarn

## Overview

BugBarn is a self-hosted error-tracking service. SDKs and Alertmanager send events to the Go API, which acknowledges durable queueing; background processing normalizes and scrubs events, fingerprints them, and persists issues and events. Users then browse and manage issues, logs, releases, projects, and alerts through the web app or CLI. The README documents these capabilities; the sampled excerpts confirm key wiring and storage behavior, but do not expose every handler-to-service call, so uncertain links are omitted.

Main entry points: [`internal/storage/storage.go`](https://github.com/webwiebe/bugbarn/blob/main/internal/storage/storage.go) (SQLite storage), [`internal/api`](https://github.com/webwiebe/bugbarn/tree/main/internal/api) (HTTP API), [`internal/worker/processor.go`](https://github.com/webwiebe/bugbarn/blob/main/internal/worker/processor.go) (Event worker), [`internal/ingest/handler.go`](https://github.com/webwiebe/bugbarn/blob/main/internal/ingest/handler.go) (Ingest handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Senders and clients"]
  node_sdk["SDKs"]
end

subgraph group_ingest["Ingest processing"]
  node_ingest_handler["Ingest handler<br/>[handler.go]"]
  node_alert_adapter["Alertmanager adapter<br/>[alertmanager.go]"]
  node_spool["Durable spool<br/>[spool.go]"]
  node_normalize["Normalize and scrub<br/>[normalize.go]"]
  node_fingerprint["Fingerprint events<br/>[fingerprint.go]"]
end

subgraph group_server["API and services"]
  node_api["HTTP API"]
  node_issue_service["Issue service<br/>[service.go]"]
  node_project_service["Project service<br/>[service.go]"]
  node_sourcemaps["Source maps<br/>[symbolicate.go]"]
end

subgraph group_data["Persistence and workers"]
  node_worker["Event worker<br/>[processor.go]"]
  node_storage[("SQLite storage<br/>[storage.go]")]
  node_alert_engine["Alert evaluation<br/>[evaluator.go]"]
  node_analytics["Analytics worker<br/>[worker.go]"]
  node_retention["Event retention<br/>[worker.go]"]
  node_database[("SQLite database")]
end

subgraph group_experience["User experience"]
  node_web["Web interface<br/>[app.ts]"]
  node_cli["Command-line client<br/>[main.go]"]
end

node_alertmanager(("Alertmanager"))
node_webhook(("Alert destinations"))

node_sdk -->|"sends events"| node_api
node_alertmanager -.->|"posts alerts"| node_api
node_api -->|"dispatches ingest"| node_ingest_handler
node_ingest_handler -->|"converts alerts"| node_alert_adapter
node_ingest_handler -->|"queues payloads"| node_spool
node_worker -->|"reads events"| node_spool
node_worker -->|"normalizes events"| node_normalize
node_worker -->|"fingerprints events"| node_fingerprint
node_worker -->|"persists results"| node_storage
node_issue_service -->|"reads and writes"| node_storage
node_project_service -->|"reads and writes"| node_storage
node_alert_engine -->|"loads rules"| node_storage
node_alert_engine -.->|"delivers alerts"| node_webhook
node_analytics -->|"stores analytics"| node_storage
node_retention -->|"deletes expired events"| node_storage
node_sourcemaps -->|"uses source maps"| node_storage
node_api -->|"dispatches issue operations"| node_issue_service
node_api -->|"dispatches project operations"| node_project_service
node_web -->|"calls endpoints"| node_api
node_cli -->|"calls endpoints"| node_api
node_storage -->|"reads and writes"| node_database

click node_sdk "https://github.com/webwiebe/bugbarn/tree/main/sdks"
click node_api "https://github.com/webwiebe/bugbarn/tree/main/internal/api"
click node_ingest_handler "https://github.com/webwiebe/bugbarn/blob/main/internal/ingest/handler.go"
click node_alert_adapter "https://github.com/webwiebe/bugbarn/blob/main/internal/ingest/alertmanager.go"
click node_spool "https://github.com/webwiebe/bugbarn/blob/main/internal/spool/spool.go"
click node_worker "https://github.com/webwiebe/bugbarn/blob/main/internal/worker/processor.go"
click node_normalize "https://github.com/webwiebe/bugbarn/blob/main/internal/normalize/normalize.go"
click node_fingerprint "https://github.com/webwiebe/bugbarn/blob/main/internal/fingerprint/fingerprint.go"
click node_storage "https://github.com/webwiebe/bugbarn/blob/main/internal/storage/storage.go"
click node_issue_service "https://github.com/webwiebe/bugbarn/blob/main/internal/service/issues/service.go"
click node_project_service "https://github.com/webwiebe/bugbarn/blob/main/internal/service/projects/service.go"
click node_alert_engine "https://github.com/webwiebe/bugbarn/blob/main/internal/alert/evaluator.go"
click node_analytics "https://github.com/webwiebe/bugbarn/blob/main/internal/analytics/worker.go"
click node_retention "https://github.com/webwiebe/bugbarn/blob/main/internal/retention/worker.go"
click node_sourcemaps "https://github.com/webwiebe/bugbarn/blob/main/internal/sourcemap/symbolicate.go"
click node_web "https://github.com/webwiebe/bugbarn/blob/main/web/src/app.ts"
click node_cli "https://github.com/webwiebe/bugbarn/blob/main/cmd/bb/main.go"

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 toneBlue
class node_ingest_handler,node_alert_adapter,node_spool,node_normalize,node_fingerprint toneAmber
class node_api,node_issue_service,node_project_service,node_sourcemaps toneMint
class node_worker,node_storage,node_alert_engine,node_analytics,node_retention,node_database toneRose
class node_web,node_cli,node_alertmanager,node_webhook toneIndigo
```

## Components

### Senders and clients

- [SDKs](https://github.com/webwiebe/bugbarn/tree/main/sdks): `sdks`

### Ingest processing

- [Ingest handler](https://github.com/webwiebe/bugbarn/blob/main/internal/ingest/handler.go): `internal/ingest/handler.go`
- [Alertmanager adapter](https://github.com/webwiebe/bugbarn/blob/main/internal/ingest/alertmanager.go): `internal/ingest/alertmanager.go`
- [Durable spool](https://github.com/webwiebe/bugbarn/blob/main/internal/spool/spool.go): `internal/spool/spool.go`
- [Normalize and scrub](https://github.com/webwiebe/bugbarn/blob/main/internal/normalize/normalize.go): `internal/normalize/normalize.go`
- [Fingerprint events](https://github.com/webwiebe/bugbarn/blob/main/internal/fingerprint/fingerprint.go): `internal/fingerprint/fingerprint.go`

### API and services

- [HTTP API](https://github.com/webwiebe/bugbarn/tree/main/internal/api): `internal/api`
- [Issue service](https://github.com/webwiebe/bugbarn/blob/main/internal/service/issues/service.go): `internal/service/issues/service.go`
- [Project service](https://github.com/webwiebe/bugbarn/blob/main/internal/service/projects/service.go): `internal/service/projects/service.go`
- [Source maps](https://github.com/webwiebe/bugbarn/blob/main/internal/sourcemap/symbolicate.go): `internal/sourcemap/symbolicate.go`

### Persistence and workers

- [Event worker](https://github.com/webwiebe/bugbarn/blob/main/internal/worker/processor.go): `internal/worker/processor.go`
- [SQLite storage](https://github.com/webwiebe/bugbarn/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Alert evaluation](https://github.com/webwiebe/bugbarn/blob/main/internal/alert/evaluator.go): `internal/alert/evaluator.go`
- [Analytics worker](https://github.com/webwiebe/bugbarn/blob/main/internal/analytics/worker.go): `internal/analytics/worker.go`
- [Event retention](https://github.com/webwiebe/bugbarn/blob/main/internal/retention/worker.go): `internal/retention/worker.go`
- **SQLite database**

### User experience

- [Web interface](https://github.com/webwiebe/bugbarn/blob/main/web/src/app.ts): `web/src/app.ts`
- [Command-line client](https://github.com/webwiebe/bugbarn/blob/main/cmd/bb/main.go): `cmd/bb/main.go`

### Other components

- **Alertmanager**
- **Alert destinations**

## Connections

- SDKs → HTTP API: sends events
- Alertmanager → HTTP API: posts alerts
- HTTP API → Ingest handler: dispatches ingest
- Ingest handler → Alertmanager adapter: converts alerts
- Ingest handler → Durable spool: queues payloads
- Event worker → Durable spool: reads events
- Event worker → Normalize and scrub: normalizes events
- Event worker → Fingerprint events: fingerprints events
- Event worker → SQLite storage: persists results
- Issue service → SQLite storage: reads and writes
- Project service → SQLite storage: reads and writes
- Alert evaluation → SQLite storage: loads rules
- Alert evaluation → Alert destinations: delivers alerts
- Analytics worker → SQLite storage: stores analytics
- Event retention → SQLite storage: deletes expired events
- Source maps → SQLite storage: uses source maps
- HTTP API → Issue service: dispatches issue operations
- HTTP API → Project service: dispatches project operations
- Web interface → HTTP API: calls endpoints
- Command-line client → HTTP API: calls endpoints
- SQLite storage → SQLite database: reads and writes