# juderozario08/faultkeeper architecture

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

- Interactive diagram: https://gitdiagram.com/juderozario08/faultkeeper
- Repository: https://github.com/juderozario08/faultkeeper
- Video tour (about a minute): https://gitdiagram.com/juderozario08/faultkeeper/video

## Overview

Faultkeeper is a self-hosted Sentry-compatible error-monitoring product. An application sends an event envelope to the ingest edge; queued processing normalizes and groups events into issues, persists them, and publishes updates for the authenticated dashboard. Users browse issue lists and details, inspect event context and charts, manage projects, and request root-cause insights. The README documents Kafka, ClickHouse, a Rust ingest edge, and a first-party SDK as later-phase capabilities; those implementations are not present in the supplied tree. Edges reflect the excerpts, SOURCE INDEX references, or README; unsampled internals are represented only where documented.

Main entry points: [`backend/issues/models.py`](https://github.com/juderozario08/faultkeeper/blob/main/backend/issues/models.py) (Issues and events), [`backend/processing/pipeline.py`](https://github.com/juderozario08/faultkeeper/blob/main/backend/processing/pipeline.py) (Event pipeline), [`backend/ingest/views.py`](https://github.com/juderozario08/faultkeeper/blob/main/backend/ingest/views.py) (Envelope ingest), [`backend/ingest/queue.py`](https://github.com/juderozario08/faultkeeper/blob/main/backend/ingest/queue.py) (Ingest queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Event ingestion"]
  node_ingest_api["Envelope ingest<br/>[views.py]"]
  node_ingest_auth["DSN authentication<br/>[auth.py]"]
  node_ingest_queue["Ingest queue<br/>[queue.py]"]
end

subgraph group_processing["Issue processing"]
  node_event_pipeline["Event pipeline<br/>[pipeline.py]"]
  node_normalization["Event normalization<br/>[normalize.py]"]
  node_grouping["Fingerprint grouping<br/>[grouping.py]"]
  node_processing_tasks["Background processing<br/>[tasks.py]"]
end

subgraph group_domain["Projects and insights"]
  node_issue_store[("Issues and events<br/>[models.py]")]
  node_organizations[("Organizations and projects<br/>[models.py]")]
  node_issue_api["Issue API<br/>[views.py]"]
  node_insights_api["Issue Insights<br/>[views.py]"]
  node_insights_provider["Insight providers<br/>[providers.py]"]
end

subgraph group_realtime["Live delivery"]
  node_realtime_publish["Update publisher<br/>[publish.py]"]
  node_stream_consumer["Project WebSocket<br/>[consumers.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Dashboard routing<br/>[App.tsx]"]
  node_issue_list["Issue list and charts<br/>[IssuesPage.tsx]"]
  node_issue_detail["Issue detail"]
  node_api_hooks["API data hooks<br/>[hooks.ts]"]
  node_api_client["HTTP client<br/>[client.ts]"]
  node_project_stream["Live stream hook"]
end

node_application(("Reporting application"))
node_dashboard_user(("Dashboard user"))
node_postgres[("PostgreSQL")]
node_llm["LLM provider"]
node_kafka["Kafka pipeline"]
node_clickhouse[("ClickHouse analytics")]
node_rust_edge["Rust ingest edge"]
node_first_party_sdk["Faultkeeper JS SDK"]

node_application -->|"sends envelopes"| node_ingest_api
node_ingest_api -.->|"authenticates keys"| node_ingest_auth
node_ingest_api -.->|"queues events"| node_ingest_queue
node_ingest_queue -.->|"dispatches events"| node_processing_tasks
node_processing_tasks -->|"calls processor"| node_event_pipeline
node_event_pipeline -->|"normalizes"| node_normalization
node_event_pipeline -->|"fingerprints"| node_grouping
node_event_pipeline -->|"saves events"| node_issue_store
node_event_pipeline -->|"publishes updates"| node_realtime_publish
node_ingest_auth -->|"checks project keys"| node_organizations
node_issue_store -->|"references projects"| node_organizations
node_issue_api -.->|"serves issue data"| node_issue_store
node_insights_api -.->|"requests analysis"| node_insights_provider
node_insights_api -.->|"uses issue context"| node_issue_store
node_insights_provider -.->|"queries model"| node_llm
node_realtime_publish -->|"publishes updates"| node_stream_consumer
node_dashboard_user -->|"uses dashboard"| node_dashboard_app
node_dashboard_app -->|"routes to list"| node_issue_list
node_dashboard_app -->|"routes to detail"| node_issue_detail
node_issue_list -->|"loads issues"| node_api_hooks
node_issue_detail -->|"loads details"| node_api_hooks
node_api_hooks -->|"makes requests"| node_api_client
node_issue_list -->|"subscribes live"| node_project_stream
node_project_stream -.->|"receives updates"| node_stream_consumer
node_issue_store -->|"persists records"| node_postgres
node_ingest_queue -.->|"future event bus"| node_kafka
node_issue_store -.->|"future analytics"| node_clickhouse
node_rust_edge -.->|"future ingest edge"| node_ingest_api
node_first_party_sdk -.->|"sends events"| node_ingest_api

click node_ingest_api "https://github.com/juderozario08/faultkeeper/blob/main/backend/ingest/views.py"
click node_ingest_auth "https://github.com/juderozario08/faultkeeper/blob/main/backend/ingest/auth.py"
click node_ingest_queue "https://github.com/juderozario08/faultkeeper/blob/main/backend/ingest/queue.py"
click node_event_pipeline "https://github.com/juderozario08/faultkeeper/blob/main/backend/processing/pipeline.py"
click node_normalization "https://github.com/juderozario08/faultkeeper/blob/main/backend/processing/normalize.py"
click node_grouping "https://github.com/juderozario08/faultkeeper/blob/main/backend/processing/grouping.py"
click node_processing_tasks "https://github.com/juderozario08/faultkeeper/blob/main/backend/processing/tasks.py"
click node_issue_store "https://github.com/juderozario08/faultkeeper/blob/main/backend/issues/models.py"
click node_organizations "https://github.com/juderozario08/faultkeeper/blob/main/backend/organizations/models.py"
click node_issue_api "https://github.com/juderozario08/faultkeeper/blob/main/backend/issues/views.py"
click node_insights_api "https://github.com/juderozario08/faultkeeper/blob/main/backend/insights/views.py"
click node_insights_provider "https://github.com/juderozario08/faultkeeper/blob/main/backend/insights/providers.py"
click node_realtime_publish "https://github.com/juderozario08/faultkeeper/blob/main/backend/realtime/publish.py"
click node_stream_consumer "https://github.com/juderozario08/faultkeeper/blob/main/backend/realtime/consumers.py"
click node_dashboard_app "https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/App.tsx"
click node_issue_list "https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/pages/IssuesPage.tsx"
click node_issue_detail "https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/pages/issue/IssueDetailPage.tsx"
click node_api_hooks "https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/api/hooks.ts"
click node_api_client "https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/api/client.ts"
click node_project_stream "https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/realtime/useProjectStream.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_ingest_api,node_ingest_auth,node_ingest_queue,node_dashboard_user toneBlue
class node_event_pipeline,node_normalization,node_grouping,node_processing_tasks,node_postgres,node_clickhouse toneAmber
class node_issue_store,node_organizations,node_issue_api,node_insights_api,node_insights_provider toneMint
class node_realtime_publish,node_stream_consumer toneRose
class node_dashboard_app,node_issue_list,node_issue_detail,node_api_hooks,node_api_client,node_project_stream,node_application,node_llm,node_kafka,node_rust_edge,node_first_party_sdk toneIndigo
```

## Components

### Event ingestion

- [Envelope ingest](https://github.com/juderozario08/faultkeeper/blob/main/backend/ingest/views.py): `backend/ingest/views.py`
- [DSN authentication](https://github.com/juderozario08/faultkeeper/blob/main/backend/ingest/auth.py): `backend/ingest/auth.py`
- [Ingest queue](https://github.com/juderozario08/faultkeeper/blob/main/backend/ingest/queue.py): `backend/ingest/queue.py`

### Issue processing

- [Event pipeline](https://github.com/juderozario08/faultkeeper/blob/main/backend/processing/pipeline.py): `backend/processing/pipeline.py`
- [Event normalization](https://github.com/juderozario08/faultkeeper/blob/main/backend/processing/normalize.py): `backend/processing/normalize.py`
- [Fingerprint grouping](https://github.com/juderozario08/faultkeeper/blob/main/backend/processing/grouping.py): `backend/processing/grouping.py`
- [Background processing](https://github.com/juderozario08/faultkeeper/blob/main/backend/processing/tasks.py): `backend/processing/tasks.py`

### Projects and insights

- [Issues and events](https://github.com/juderozario08/faultkeeper/blob/main/backend/issues/models.py): `backend/issues/models.py`
- [Organizations and projects](https://github.com/juderozario08/faultkeeper/blob/main/backend/organizations/models.py): `backend/organizations/models.py`
- [Issue API](https://github.com/juderozario08/faultkeeper/blob/main/backend/issues/views.py): `backend/issues/views.py`
- [Issue Insights](https://github.com/juderozario08/faultkeeper/blob/main/backend/insights/views.py): `backend/insights/views.py`
- [Insight providers](https://github.com/juderozario08/faultkeeper/blob/main/backend/insights/providers.py): `backend/insights/providers.py`

### Live delivery

- [Update publisher](https://github.com/juderozario08/faultkeeper/blob/main/backend/realtime/publish.py): `backend/realtime/publish.py`
- [Project WebSocket](https://github.com/juderozario08/faultkeeper/blob/main/backend/realtime/consumers.py): `backend/realtime/consumers.py`

### Dashboard

- [Dashboard routing](https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Issue list and charts](https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/pages/IssuesPage.tsx): `frontend/src/pages/IssuesPage.tsx`
- [Issue detail](https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/pages/issue/IssueDetailPage.tsx): `frontend/src/pages/issue/IssueDetailPage.tsx`
- [API data hooks](https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/api/hooks.ts): `frontend/src/api/hooks.ts`
- [HTTP client](https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Live stream hook](https://github.com/juderozario08/faultkeeper/blob/main/frontend/src/realtime/useProjectStream.ts): `frontend/src/realtime/useProjectStream.ts`

### Other components

- **Reporting application**
- **Dashboard user**
- **PostgreSQL**
- **LLM provider**
- **Kafka pipeline**
- **ClickHouse analytics**
- **Rust ingest edge**
- **Faultkeeper JS SDK**

## Connections

- Reporting application → Envelope ingest: sends envelopes (evidence: `README.md`)
- Envelope ingest → DSN authentication: authenticates keys
- Envelope ingest → Ingest queue: queues events
- Ingest queue → Background processing: dispatches events
- Background processing → Event pipeline: calls processor (evidence: `backend/processing/tasks.py`)
- Event pipeline → Event normalization: normalizes (evidence: `backend/processing/pipeline.py`)
- Event pipeline → Fingerprint grouping: fingerprints (evidence: `backend/processing/pipeline.py`)
- Event pipeline → Issues and events: saves events (evidence: `backend/processing/pipeline.py`)
- Event pipeline → Update publisher: publishes updates (evidence: `backend/processing/pipeline.py`)
- DSN authentication → Organizations and projects: checks project keys (evidence: `backend/ingest/auth.py`)
- Issues and events → Organizations and projects: references projects (evidence: `backend/issues/models.py`)
- Issue API → Issues and events: serves issue data
- Issue Insights → Insight providers: requests analysis
- Issue Insights → Issues and events: uses issue context
- Insight providers → LLM provider: queries model
- Update publisher → Project WebSocket: publishes updates (evidence: `backend/realtime/publish.py`)
- Dashboard user → Dashboard routing: uses dashboard (evidence: `README.md`)
- Dashboard routing → Issue list and charts: routes to list (evidence: `frontend/src/App.tsx`)
- Dashboard routing → Issue detail: routes to detail (evidence: `frontend/src/App.tsx`)
- Issue list and charts → API data hooks: loads issues (evidence: `frontend/src/pages/IssuesPage.tsx`)
- Issue detail → API data hooks: loads details (evidence: `frontend/src/pages/issue/IssueDetailPage.tsx`)
- API data hooks → HTTP client: makes requests (evidence: `frontend/src/api/hooks.ts`)
- Issue list and charts → Live stream hook: subscribes live (evidence: `frontend/src/pages/IssuesPage.tsx`)
- Live stream hook → Project WebSocket: receives updates
- Issues and events → PostgreSQL: persists records (evidence: `README.md`)
- Ingest queue → Kafka pipeline: future event bus (evidence: `README.md`)
- Issues and events → ClickHouse analytics: future analytics (evidence: `README.md`)
- Rust ingest edge → Envelope ingest: future ingest edge (evidence: `README.md`)
- Faultkeeper JS SDK → Envelope ingest: sends events (evidence: `README.md`)
