# santhoshjanan/veerabahu architecture

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

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

## Overview

Veerabahu is a local human-in-the-loop DNS-domain enrichment sidecar: it observes resolved domains from Pi-hole or AdGuard Home, investigates them through reputation sources, and presents recommendations for human review. Approved domains appear in a blocklist the gatekeeper pulls; Veerabahu does not change gatekeeper rules. The graph preserves this workflow plus onboarding/settings, review and audit, live events, and persistence. Several links are documented in the README; unsampled implementation details are not inferred as direct calls.

Main entry points: [`src/lib/server/governor/drainer.ts`](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/governor/drainer.ts) (Assessment drainer), [`src/lib/server/db/repo.ts`](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/db/repo.ts) (Application database), [`src/lib/server/pipeline/review.ts`](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/pipeline/review.ts) (Review decisions), [`src/lib/server/settings/store.ts`](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/settings/store.ts) (Encrypted settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_observe["Domain observation"]
  node_scheduler["Ingestion scheduler<br/>[scheduler.ts]"]
  node_gatekeeper_adapter["Gatekeeper adapters"]
end

subgraph group_assess["Enrichment and assessment"]
  node_dns["DNS enrichment<br/>[dns.ts]"]
  node_drainer["Assessment drainer<br/>[drainer.ts]"]
  node_sources["Reputation sources"]
  node_rate_state["Source rate state<br/>[rate-state.ts]"]
  node_evaluate["Domain evaluation<br/>[evaluate.ts]"]
  node_scoring["Scoring<br/>[score.ts]"]
end

subgraph group_review["Human review"]
  node_review_ui["Review interface<br/>[ReviewEntry.svelte]"]
  node_review_routes["Review endpoints<br/>[+server.ts]"]
  node_review_service["Review decisions<br/>[review.ts]"]
  node_publisher["Blocklist publisher<br/>[blocklist.ts]"]
end

subgraph group_platform["Application services"]
  node_auth["Local authentication<br/>[auth.ts]"]
  node_settings_store["Encrypted settings<br/>[store.ts]"]
  node_config["Runtime configuration<br/>[config.ts]"]
  node_database[("Application database<br/>[repo.ts]")]
  node_audit["Audit log<br/>[log.ts]"]
  node_events["Live event bus<br/>[events.ts]"]
end

subgraph group_experience["Web experience"]
  node_settings_ui["Setup and settings<br/>[+page.server.ts]"]
  node_event_stream["Event stream endpoint<br/>[+server.ts]"]
  node_dashboard["Domain and queue views<br/>[dashboard.ts]"]
end

node_gatekeeper["Pi-hole / AdGuard"]
node_gatekeeper_pull(("Gatekeeper adlist pull"))
node_review_actor(("Administrator"))

node_gatekeeper -->|"serves domain data"| node_gatekeeper_adapter
node_scheduler -.->|"reads resolved domains"| node_gatekeeper_adapter
node_scheduler -.->|"schedules assessment"| node_drainer
node_drainer -->|"checks call limits"| node_rate_state
node_drainer -->|"loads queued domains"| node_database
node_drainer -->|"requests assessments"| node_sources
node_drainer -->|"evaluates domain"| node_evaluate
node_evaluate -->|"uses scoring"| node_scoring
node_drainer -->|"publishes progress"| node_events
node_review_ui -->|"submits decision"| node_review_routes
node_review_routes -.->|"dispatches decision"| node_review_service
node_review_service -->|"records decision"| node_database
node_review_service -->|"appends audit entry"| node_audit
node_review_service -->|"publishes decision"| node_events
node_publisher -.->|"reads approved domains"| node_database
node_gatekeeper_pull -->|"pulls published list"| node_publisher
node_settings_ui -->|"saves setup"| node_settings_store
node_settings_store -->|"stores settings and secrets"| node_database
node_settings_store -->|"loads runtime config"| node_config
node_auth -->|"stores sessions"| node_database
node_review_actor -->|"reviews recommendations"| node_review_ui
node_event_stream -.->|"streams updates"| node_events
node_dashboard -.->|"reads domain summaries"| node_database

click node_scheduler "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/ingestion/scheduler.ts"
click node_gatekeeper_adapter "https://github.com/santhoshjanan/veerabahu/tree/main/src/lib/server/adapters/gatekeeper"
click node_dns "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/enrichment/dns.ts"
click node_drainer "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/governor/drainer.ts"
click node_sources "https://github.com/santhoshjanan/veerabahu/tree/main/src/lib/server/reputation"
click node_rate_state "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/governor/rate-state.ts"
click node_evaluate "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/pipeline/evaluate.ts"
click node_scoring "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/scoring/score.ts"
click node_review_ui "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/components/ReviewEntry.svelte"
click node_review_routes "https://github.com/santhoshjanan/veerabahu/blob/main/src/routes/api/review/%5Bdomain%5D/%2Bserver.ts"
click node_review_service "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/pipeline/review.ts"
click node_publisher "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/publisher/blocklist.ts"
click node_settings_ui "https://github.com/santhoshjanan/veerabahu/blob/main/src/routes/setup/%2Bpage.server.ts"
click node_auth "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/auth.ts"
click node_settings_store "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/settings/store.ts"
click node_config "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/config.ts"
click node_database "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/db/repo.ts"
click node_audit "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/audit/log.ts"
click node_events "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/events.ts"
click node_event_stream "https://github.com/santhoshjanan/veerabahu/blob/main/src/routes/events/%2Bserver.ts"
click node_dashboard "https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/pipeline/dashboard.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_scheduler,node_gatekeeper_adapter toneBlue
class node_dns,node_drainer,node_sources,node_rate_state,node_evaluate,node_scoring toneAmber
class node_review_ui,node_review_routes,node_review_service,node_publisher toneMint
class node_auth,node_settings_store,node_config,node_database,node_audit,node_events toneRose
class node_settings_ui,node_event_stream,node_dashboard,node_gatekeeper,node_gatekeeper_pull,node_review_actor toneIndigo
```

## Components

### Domain observation

- [Ingestion scheduler](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/ingestion/scheduler.ts): `src/lib/server/ingestion/scheduler.ts`
- [Gatekeeper adapters](https://github.com/santhoshjanan/veerabahu/tree/main/src/lib/server/adapters/gatekeeper): `src/lib/server/adapters/gatekeeper`

### Enrichment and assessment

- [DNS enrichment](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/enrichment/dns.ts): `src/lib/server/enrichment/dns.ts`
- [Assessment drainer](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/governor/drainer.ts): `src/lib/server/governor/drainer.ts`
- [Reputation sources](https://github.com/santhoshjanan/veerabahu/tree/main/src/lib/server/reputation): `src/lib/server/reputation`
- [Source rate state](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/governor/rate-state.ts): `src/lib/server/governor/rate-state.ts`
- [Domain evaluation](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/pipeline/evaluate.ts): `src/lib/server/pipeline/evaluate.ts`
- [Scoring](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/scoring/score.ts): `src/lib/server/scoring/score.ts`

### Human review

- [Review interface](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/components/ReviewEntry.svelte): `src/lib/components/ReviewEntry.svelte`
- [Review endpoints](https://github.com/santhoshjanan/veerabahu/blob/main/src/routes/api/review/%5Bdomain%5D/%2Bserver.ts): `src/routes/api/review/[domain]/+server.ts`
- [Review decisions](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/pipeline/review.ts): `src/lib/server/pipeline/review.ts`
- [Blocklist publisher](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/publisher/blocklist.ts): `src/lib/server/publisher/blocklist.ts`

### Application services

- [Local authentication](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/auth.ts): `src/lib/server/auth.ts`
- [Encrypted settings](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/settings/store.ts): `src/lib/server/settings/store.ts`
- [Runtime configuration](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/config.ts): `src/lib/server/config.ts`
- [Application database](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/db/repo.ts): `src/lib/server/db/repo.ts`
- [Audit log](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/audit/log.ts): `src/lib/server/audit/log.ts`
- [Live event bus](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/events.ts): `src/lib/server/events.ts`

### Web experience

- [Setup and settings](https://github.com/santhoshjanan/veerabahu/blob/main/src/routes/setup/%2Bpage.server.ts): `src/routes/setup/+page.server.ts`
- [Event stream endpoint](https://github.com/santhoshjanan/veerabahu/blob/main/src/routes/events/%2Bserver.ts): `src/routes/events/+server.ts`
- [Domain and queue views](https://github.com/santhoshjanan/veerabahu/blob/main/src/lib/server/pipeline/dashboard.ts): `src/lib/server/pipeline/dashboard.ts`

### Other components

- **Pi-hole / AdGuard**
- **Gatekeeper adlist pull**
- **Administrator**

## Connections

- Pi-hole / AdGuard → Gatekeeper adapters: serves domain data (evidence: `README.md`)
- Ingestion scheduler → Gatekeeper adapters: reads resolved domains
- Ingestion scheduler → Assessment drainer: schedules assessment
- Assessment drainer → Source rate state: checks call limits (evidence: `src/lib/server/governor/drainer.ts`)
- Assessment drainer → Application database: loads queued domains (evidence: `src/lib/server/governor/drainer.ts`)
- Assessment drainer → Reputation sources: requests assessments (evidence: `src/lib/server/governor/drainer.ts`)
- Assessment drainer → Domain evaluation: evaluates domain (evidence: `src/lib/server/governor/drainer.ts`)
- Domain evaluation → Scoring: uses scoring (evidence: `src/lib/server/pipeline/evaluate.ts`)
- Assessment drainer → Live event bus: publishes progress (evidence: `src/lib/server/governor/drainer.ts`)
- Review interface → Review endpoints: submits decision (evidence: `src/lib/components/ReviewEntry.svelte`)
- Review endpoints → Review decisions: dispatches decision
- Review decisions → Application database: records decision (evidence: `src/lib/server/pipeline/review.ts`)
- Review decisions → Audit log: appends audit entry (evidence: `src/lib/server/pipeline/review.ts`)
- Review decisions → Live event bus: publishes decision (evidence: `src/lib/server/pipeline/review.ts`)
- Blocklist publisher → Application database: reads approved domains
- Gatekeeper adlist pull → Blocklist publisher: pulls published list (evidence: `README.md`)
- Setup and settings → Encrypted settings: saves setup (evidence: `src/routes/setup/+page.server.ts`)
- Encrypted settings → Application database: stores settings and secrets (evidence: `src/lib/server/settings/store.ts`)
- Encrypted settings → Runtime configuration: loads runtime config (evidence: `src/lib/server/settings/store.ts`)
- Local authentication → Application database: stores sessions (evidence: `src/lib/server/auth.ts`)
- Administrator → Review interface: reviews recommendations (evidence: `README.md`)
- Event stream endpoint → Live event bus: streams updates
- Domain and queue views → Application database: reads domain summaries
