# narfect/muninn architecture

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

- Interactive diagram: https://gitdiagram.com/narfect/muninn
- Repository: https://github.com/narfect/muninn

## Overview

Muninn is an incident-response copilot: responders open an alert, compare cold and memory-grounded warm triage, review a cited brief, then resolve the incident so its outcome is retained for future recall. The architecture separates browser workflows, HTTP/API handling, incident and triage services, reasoning and memory, and persistence/authentication. The README documents dashboards, role-based access, and optional Groq, Hindsight, and Supabase paths. Some runtime wiring is unsampled, so links for those documented capabilities cite the README rather than implying unobserved calls.

Main entry points: [`backend/api/routes.py`](https://github.com/narfect/muninn/blob/master/backend/api/routes.py) (API handlers), [`backend/server.py`](https://github.com/narfect/muninn/blob/master/backend/server.py) (HTTP server), [`backend/services/metrics.py`](https://github.com/narfect/muninn/blob/master/backend/services/metrics.py) (MTTR and learning metrics), [`backend/llm/agent.py`](https://github.com/narfect/muninn/blob/master/backend/llm/agent.py) (Triage agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Responder experience"]
  node_spa["Muninn web app<br/>[app.js]"]
  node_auth_ui["Account interface<br/>[auth.js]"]
  node_insights["Insights dashboard<br/>[socviz.js]"]
end

subgraph group_api["HTTP and workflows"]
  node_http["HTTP server<br/>[server.py]"]
  node_router["Request router<br/>[router.py]"]
  node_api_handlers["API handlers<br/>[routes.py]"]
  node_incident_service["Incident workflows<br/>[incidents.py]"]
  node_triage_service["Triage workflow<br/>[triage.py]"]
  node_metrics["MTTR and learning metrics<br/>[metrics.py]"]
end

subgraph group_memory["Triage and memory"]
  node_agent["Triage agent<br/>[agent.py]"]
  node_reasoner["Reasoner backends<br/>[client.py]"]
  node_memory_factory["Memory selection<br/>[base.py]"]
  node_recall["Memory retrieval<br/>[retrieval.py]"]
  node_local_memory["Local memory store<br/>[local_store.py]"]
  node_hindsight_store["Hindsight memory store<br/>[hindsight_store.py]"]
end

subgraph group_state["State and identity"]
  node_sqlite[("SQLite incident store<br/>[db.py]")]
  node_auth_facade["Unified authentication<br/>[auth_unified.py]"]
  node_local_auth["Local authentication<br/>[auth.py]"]
  node_supabase_auth["Supabase authentication<br/>[supabase_auth.py]"]
end

subgraph group_integrations["External backends"]
  node_hindsight_client["Hindsight client"]
  node_supabase_client["Supabase transport<br/>[supabase_client.py]"]
  node_groq["Groq API"]
  node_supabase["Supabase services"]
end

node_responder(("On-call responder"))

node_responder -->|"uses"| node_spa
node_spa -->|"calls API"| node_http
node_auth_ui -->|"authenticates"| node_http
node_insights -->|"loads insights"| node_http
node_http -->|"dispatches requests"| node_router
node_router -->|"routes requests"| node_api_handlers
node_api_handlers -->|"handles account actions"| node_auth_facade
node_api_handlers -->|"handles incident actions"| node_incident_service
node_api_handlers -->|"runs triage"| node_triage_service
node_api_handlers -->|"serves insights"| node_metrics
node_incident_service -->|"reads and writes"| node_sqlite
node_triage_service -->|"requests triage"| node_agent
node_agent -->|"reasons over alert"| node_reasoner
node_agent -->|"recalls context"| node_memory_factory
node_memory_factory -->|"selects local"| node_local_memory
node_memory_factory -->|"selects Hindsight"| node_hindsight_store
node_hindsight_store -->|"uses transport"| node_hindsight_client
node_local_memory -->|"retrieves memories"| node_recall
node_metrics -->|"reads incident data"| node_sqlite
node_metrics -->|"derives trends"| node_incident_service
node_auth_facade -->|"delegates locally"| node_local_auth
node_auth_facade -->|"delegates remotely"| node_supabase_auth
node_supabase_auth -->|"calls Auth API"| node_supabase_client
node_local_auth -->|"stores local accounts"| node_sqlite
node_supabase_client -->|"uses Auth and REST"| node_supabase
node_reasoner -.->|"calls model API"| node_groq
node_hindsight_client -.-> node_supabase

click node_spa "https://github.com/narfect/muninn/blob/master/static/app.js"
click node_auth_ui "https://github.com/narfect/muninn/blob/master/static/auth.js"
click node_insights "https://github.com/narfect/muninn/blob/master/static/socviz.js"
click node_http "https://github.com/narfect/muninn/blob/master/backend/server.py"
click node_router "https://github.com/narfect/muninn/blob/master/backend/router.py"
click node_api_handlers "https://github.com/narfect/muninn/blob/master/backend/api/routes.py"
click node_incident_service "https://github.com/narfect/muninn/blob/master/backend/services/incidents.py"
click node_triage_service "https://github.com/narfect/muninn/blob/master/backend/services/triage.py"
click node_agent "https://github.com/narfect/muninn/blob/master/backend/llm/agent.py"
click node_reasoner "https://github.com/narfect/muninn/blob/master/backend/llm/client.py"
click node_memory_factory "https://github.com/narfect/muninn/blob/master/backend/memory/base.py"
click node_recall "https://github.com/narfect/muninn/blob/master/backend/memory/retrieval.py"
click node_local_memory "https://github.com/narfect/muninn/blob/master/backend/memory/local_store.py"
click node_hindsight_store "https://github.com/narfect/muninn/blob/master/backend/memory/hindsight_store.py"
click node_hindsight_client "https://github.com/narfect/muninn/blob/master/backend/memory/hindsight_client.py"
click node_metrics "https://github.com/narfect/muninn/blob/master/backend/services/metrics.py"
click node_sqlite "https://github.com/narfect/muninn/blob/master/backend/db.py"
click node_auth_facade "https://github.com/narfect/muninn/blob/master/backend/services/auth_unified.py"
click node_local_auth "https://github.com/narfect/muninn/blob/master/backend/services/auth.py"
click node_supabase_auth "https://github.com/narfect/muninn/blob/master/backend/services/supabase_auth.py"
click node_supabase_client "https://github.com/narfect/muninn/blob/master/backend/services/supabase_client.py"

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_spa,node_auth_ui,node_insights toneBlue
class node_http,node_router,node_api_handlers,node_incident_service,node_triage_service,node_metrics toneAmber
class node_agent,node_reasoner,node_memory_factory,node_recall,node_local_memory,node_hindsight_store toneMint
class node_sqlite,node_auth_facade,node_local_auth,node_supabase_auth toneRose
class node_hindsight_client,node_supabase_client,node_groq,node_supabase,node_responder toneIndigo
```

## Components

### Responder experience

- [Muninn web app](https://github.com/narfect/muninn/blob/master/static/app.js): `static/app.js`
- [Account interface](https://github.com/narfect/muninn/blob/master/static/auth.js): `static/auth.js`
- [Insights dashboard](https://github.com/narfect/muninn/blob/master/static/socviz.js): `static/socviz.js`

### HTTP and workflows

- [HTTP server](https://github.com/narfect/muninn/blob/master/backend/server.py): `backend/server.py`
- [Request router](https://github.com/narfect/muninn/blob/master/backend/router.py): `backend/router.py`
- [API handlers](https://github.com/narfect/muninn/blob/master/backend/api/routes.py): `backend/api/routes.py`
- [Incident workflows](https://github.com/narfect/muninn/blob/master/backend/services/incidents.py): `backend/services/incidents.py`
- [Triage workflow](https://github.com/narfect/muninn/blob/master/backend/services/triage.py): `backend/services/triage.py`
- [MTTR and learning metrics](https://github.com/narfect/muninn/blob/master/backend/services/metrics.py): `backend/services/metrics.py`

### Triage and memory

- [Triage agent](https://github.com/narfect/muninn/blob/master/backend/llm/agent.py): `backend/llm/agent.py`
- [Reasoner backends](https://github.com/narfect/muninn/blob/master/backend/llm/client.py): `backend/llm/client.py`
- [Memory selection](https://github.com/narfect/muninn/blob/master/backend/memory/base.py): `backend/memory/base.py`
- [Memory retrieval](https://github.com/narfect/muninn/blob/master/backend/memory/retrieval.py): `backend/memory/retrieval.py`
- [Local memory store](https://github.com/narfect/muninn/blob/master/backend/memory/local_store.py): `backend/memory/local_store.py`
- [Hindsight memory store](https://github.com/narfect/muninn/blob/master/backend/memory/hindsight_store.py): `backend/memory/hindsight_store.py`

### State and identity

- [SQLite incident store](https://github.com/narfect/muninn/blob/master/backend/db.py): `backend/db.py`
- [Unified authentication](https://github.com/narfect/muninn/blob/master/backend/services/auth_unified.py): `backend/services/auth_unified.py`
- [Local authentication](https://github.com/narfect/muninn/blob/master/backend/services/auth.py): `backend/services/auth.py`
- [Supabase authentication](https://github.com/narfect/muninn/blob/master/backend/services/supabase_auth.py): `backend/services/supabase_auth.py`

### External backends

- [Hindsight client](https://github.com/narfect/muninn/blob/master/backend/memory/hindsight_client.py): `backend/memory/hindsight_client.py`
- [Supabase transport](https://github.com/narfect/muninn/blob/master/backend/services/supabase_client.py): `backend/services/supabase_client.py`
- **Groq API**
- **Supabase services**

### Other components

- **On-call responder**

## Connections

- On-call responder → Muninn web app: uses (evidence: `README.md`)
- Muninn web app → HTTP server: calls API (evidence: `README.md`)
- Account interface → HTTP server: authenticates (evidence: `README.md`)
- Insights dashboard → HTTP server: loads insights (evidence: `README.md`)
- HTTP server → Request router: dispatches requests (evidence: `backend/server.py`)
- Request router → API handlers: routes requests (evidence: `backend/router.py`)
- API handlers → Unified authentication: handles account actions (evidence: `backend/api/routes.py`)
- API handlers → Incident workflows: handles incident actions (evidence: `README.md`)
- API handlers → Triage workflow: runs triage (evidence: `README.md`)
- API handlers → MTTR and learning metrics: serves insights (evidence: `README.md`)
- Incident workflows → SQLite incident store: reads and writes (evidence: `backend/services/incidents.py`)
- Triage workflow → Triage agent: requests triage (evidence: `backend/services/triage.py`)
- Triage agent → Reasoner backends: reasons over alert (evidence: `backend/llm/agent.py`)
- Triage agent → Memory selection: recalls context (evidence: `backend/llm/agent.py`)
- Memory selection → Local memory store: selects local (evidence: `backend/memory/base.py`)
- Memory selection → Hindsight memory store: selects Hindsight (evidence: `backend/memory/base.py`)
- Hindsight memory store → Hindsight client: uses transport (evidence: `backend/memory/hindsight_store.py`)
- Local memory store → Memory retrieval: retrieves memories (evidence: `backend/memory/local_store.py`)
- MTTR and learning metrics → SQLite incident store: reads incident data (evidence: `backend/services/metrics.py`)
- MTTR and learning metrics → Incident workflows: derives trends (evidence: `backend/services/metrics.py`)
- Unified authentication → Local authentication: delegates locally (evidence: `backend/services/auth_unified.py`)
- Unified authentication → Supabase authentication: delegates remotely (evidence: `backend/services/auth_unified.py`)
- Supabase authentication → Supabase transport: calls Auth API (evidence: `backend/services/supabase_auth.py`)
- Local authentication → SQLite incident store: stores local accounts (evidence: `backend/services/auth.py`)
- Supabase transport → Supabase services: uses Auth and REST (evidence: `backend/services/supabase_client.py`)
- Reasoner backends → Groq API: calls model API (evidence: `README.md`)
- Hindsight client → Supabase services
