# warden-osint/warden architecture

> Architecture diagram of the GitHub repository warden-osint/warden, 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/warden-osint/warden
- Repository: https://github.com/warden-osint/warden

## Overview

Warden is a passive-OSINT cyber-risk assessment platform. Users confirm company assets, enable public-data sources, and launch or schedule scans; the worker collects evidence, updates findings, computes versioned KRI scores, then supports alerts, reports, and optional SIEM delivery. The graph follows documented capabilities and worker call references in the source index. Many web pages and pipeline modules were not excerpted, so uncertain implementation links are omitted or marked unverified.

Main entry points: [`apps/worker/src/jobs/run-scan.ts`](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/jobs/run-scan.ts) (Scan job), [`apps/worker/src/index.ts`](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/index.ts) (Queue worker), [`apps/worker/src/pipeline/notify.ts`](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/notify.ts) (Alert delivery), [`apps/web/src/app/api/scans/route.ts`](https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/api/scans/route.ts) (Scan API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_scan_api["Scan API<br/>[route.ts]"]
  node_scan_settings["Scan settings<br/>[page.tsx]"]
  node_findings_ui["Findings<br/>[page.tsx]"]
  node_reports_ui["Reports<br/>[page.tsx]"]
  node_user_admin["User administration<br/>[handler.ts]"]
end

subgraph group_scan["Scan processing"]
  node_worker["Queue worker<br/>[index.ts]"]
  node_scan_job["Scan job<br/>[run-scan.ts]"]
  node_collection["OSINT collection<br/>[collect.ts]"]
  node_source_integrations["Public sources"]
  node_persistence["Evidence persistence<br/>[persist.ts]"]
end

subgraph group_analysis["Analysis"]
  node_finding_resolution["Finding resolution<br/>[resolve.ts]"]
  node_scoring["KRI scoring<br/>[index.ts]"]
  node_risk_analysis["Risk analyzers"]
end

subgraph group_delivery["Notifications and reporting"]
  node_alert_rules["Alert evaluation<br/>[alerts.ts]"]
  node_notifications["Alert delivery<br/>[notify.ts]"]
  node_email["Email alerts<br/>[email-alert.ts]"]
  node_report_generation["Report generation<br/>[report.ts]"]
  node_ai_summary["AI summary<br/>[client.ts]"]
  node_siem["SIEM integration<br/>[siem.ts]"]
end

subgraph group_platform["Shared services"]
  node_database[("Supabase<br/>[supabase.ts]")]
end

node_analyst(("Analyst"))
node_openrouter{{"OpenRouter"}}
node_smtp{{"SMTP service"}}
node_splunk{{"Splunk HEC"}}

node_analyst -->|"uses"| node_dashboard
node_dashboard -.->|"launches"| node_scan_api
node_scan_settings -.->|"schedules"| node_scan_api
node_scan_api -.->|"requests scan"| node_database
node_worker -->|"polls queues"| node_database
node_worker -->|"runs scan"| node_scan_job
node_scan_job -->|"collects"| node_collection
node_collection -.->|"queries sources"| node_source_integrations
node_scan_job -->|"persists results"| node_persistence
node_scan_job -->|"resolves findings"| node_finding_resolution
node_scan_job -->|"scores scan"| node_scoring
node_finding_resolution -->|"precedes scoring"| node_scoring
node_analyst -->|"triages"| node_findings_ui
node_analyst -->|"reviews"| node_reports_ui
node_analyst -->|"manages users"| node_user_admin
node_scan_job -->|"evaluates score"| node_alert_rules
node_worker -->|"delivers alerts"| node_notifications
node_notifications -->|"builds email"| node_email
node_worker -->|"generates reports"| node_report_generation
node_report_generation -->|"requests summary"| node_ai_summary
node_ai_summary -->|"calls API"| node_openrouter
node_worker -->|"delivers events"| node_siem
node_siem -.->|"sends events"| node_splunk
node_notifications -.->|"sends mail"| node_smtp
node_risk_analysis -.->|"analyzes evidence"| node_collection

click node_dashboard "https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/(dashboard)/page.tsx"
click node_scan_api "https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/api/scans/route.ts"
click node_scan_settings "https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/(dashboard)/settings/schedule/page.tsx"
click node_findings_ui "https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/(dashboard)/findings/page.tsx"
click node_reports_ui "https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/(dashboard)/reports/%5Bid%5D/page.tsx"
click node_user_admin "https://github.com/warden-osint/warden/blob/dev/supabase/functions/manage-users/handler.ts"
click node_worker "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/index.ts"
click node_scan_job "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/jobs/run-scan.ts"
click node_collection "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/collect.ts"
click node_source_integrations "https://github.com/warden-osint/warden/tree/dev/packages/collectors/src"
click node_persistence "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/persist.ts"
click node_finding_resolution "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/resolve.ts"
click node_scoring "https://github.com/warden-osint/warden/blob/dev/packages/scoring/src/index.ts"
click node_risk_analysis "https://github.com/warden-osint/warden/tree/dev/packages/risk-analysis/src"
click node_alert_rules "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/alerts.ts"
click node_notifications "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/notify.ts"
click node_email "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/email-alert.ts"
click node_report_generation "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/report.ts"
click node_ai_summary "https://github.com/warden-osint/warden/blob/dev/packages/ai/src/client.ts"
click node_siem "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/siem.ts"
click node_database "https://github.com/warden-osint/warden/blob/dev/apps/worker/src/supabase.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_dashboard,node_scan_api,node_scan_settings,node_findings_ui,node_reports_ui,node_user_admin toneBlue
class node_worker,node_scan_job,node_collection,node_source_integrations,node_persistence toneAmber
class node_finding_resolution,node_scoring,node_risk_analysis,node_openrouter toneMint
class node_alert_rules,node_notifications,node_email,node_report_generation,node_ai_summary,node_siem toneRose
class node_database,node_analyst,node_smtp,node_splunk toneIndigo
```

## Components

### Web app

- [Dashboard](https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/(dashboard)/page.tsx): `apps/web/src/app/(dashboard)/page.tsx`
- [Scan API](https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/api/scans/route.ts): `apps/web/src/app/api/scans/route.ts`
- [Scan settings](https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/(dashboard)/settings/schedule/page.tsx): `apps/web/src/app/(dashboard)/settings/schedule/page.tsx`
- [Findings](https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/(dashboard)/findings/page.tsx): `apps/web/src/app/(dashboard)/findings/page.tsx`
- [Reports](https://github.com/warden-osint/warden/blob/dev/apps/web/src/app/(dashboard)/reports/%5Bid%5D/page.tsx): `apps/web/src/app/(dashboard)/reports/[id]/page.tsx`
- [User administration](https://github.com/warden-osint/warden/blob/dev/supabase/functions/manage-users/handler.ts): `supabase/functions/manage-users/handler.ts`

### Scan processing

- [Queue worker](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/index.ts): `apps/worker/src/index.ts`
- [Scan job](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/jobs/run-scan.ts): `apps/worker/src/jobs/run-scan.ts`
- [OSINT collection](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/collect.ts): `apps/worker/src/pipeline/collect.ts`
- [Public sources](https://github.com/warden-osint/warden/tree/dev/packages/collectors/src): `packages/collectors/src`
- [Evidence persistence](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/persist.ts): `apps/worker/src/pipeline/persist.ts`

### Analysis

- [Finding resolution](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/resolve.ts): `apps/worker/src/pipeline/resolve.ts`
- [KRI scoring](https://github.com/warden-osint/warden/blob/dev/packages/scoring/src/index.ts): `packages/scoring/src/index.ts`
- [Risk analyzers](https://github.com/warden-osint/warden/tree/dev/packages/risk-analysis/src): `packages/risk-analysis/src`

### Notifications and reporting

- [Alert evaluation](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/alerts.ts): `apps/worker/src/pipeline/alerts.ts`
- [Alert delivery](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/notify.ts): `apps/worker/src/pipeline/notify.ts`
- [Email alerts](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/email-alert.ts): `apps/worker/src/pipeline/email-alert.ts`
- [Report generation](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/report.ts): `apps/worker/src/pipeline/report.ts`
- [AI summary](https://github.com/warden-osint/warden/blob/dev/packages/ai/src/client.ts): `packages/ai/src/client.ts`
- [SIEM integration](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/pipeline/siem.ts): `apps/worker/src/pipeline/siem.ts`

### Shared services

- [Supabase](https://github.com/warden-osint/warden/blob/dev/apps/worker/src/supabase.ts): `apps/worker/src/supabase.ts`

### Other components

- **Analyst**
- **OpenRouter**
- **SMTP service**
- **Splunk HEC**

## Connections

- Analyst → Dashboard: uses (evidence: `README.md`)
- Dashboard → Scan API: launches
- Scan settings → Scan API: schedules
- Scan API → Supabase: requests scan
- Queue worker → Supabase: polls queues (evidence: `apps/worker/src/index.ts`)
- Queue worker → Scan job: runs scan (evidence: `apps/worker/src/index.ts`)
- Scan job → OSINT collection: collects (evidence: `apps/worker/src/jobs/run-scan.ts`)
- OSINT collection → Public sources: queries sources
- Scan job → Evidence persistence: persists results (evidence: `apps/worker/src/jobs/run-scan.ts`)
- Scan job → Finding resolution: resolves findings (evidence: `apps/worker/src/jobs/run-scan.ts`)
- Scan job → KRI scoring: scores scan (evidence: `apps/worker/src/jobs/run-scan.ts`)
- Finding resolution → KRI scoring: precedes scoring
- Analyst → Findings: triages (evidence: `README.md`)
- Analyst → Reports: reviews (evidence: `README.md`)
- Analyst → User administration: manages users (evidence: `README.md`)
- Scan job → Alert evaluation: evaluates score (evidence: `apps/worker/src/jobs/run-scan.ts`)
- Queue worker → Alert delivery: delivers alerts (evidence: `apps/worker/src/index.ts`)
- Alert delivery → Email alerts: builds email (evidence: `apps/worker/src/pipeline/notify.ts`)
- Queue worker → Report generation: generates reports (evidence: `apps/worker/src/index.ts`)
- Report generation → AI summary: requests summary (evidence: `apps/worker/src/pipeline/report.ts`)
- AI summary → OpenRouter: calls API (evidence: `packages/ai/src/client.ts`)
- Queue worker → SIEM integration: delivers events (evidence: `apps/worker/src/index.ts`)
- SIEM integration → Splunk HEC: sends events
- Alert delivery → SMTP service: sends mail
- Risk analyzers → OSINT collection: analyzes evidence
