# vmcchooky/safe-zone architecture

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

- Interactive diagram: https://gitdiagram.com/vmcchooky/safe-zone
- Repository: https://github.com/vmcchooky/safe-zone

## Overview

Safe Zone is a self-hosted DNS anti-phishing service: clients send DNS queries, the resolver obtains a risk verdict, and policy determines the DNS response. Operators separately manage analysis, policy, groups, reports and configuration through the API and dashboard. Threat feeds and lexical/domain signals inform verdicts; optional ML, AI and OSINT enrichment extend that decision process, while SQLite and Redis support durable state and caching. The graph follows the README and sampled entry points; wiring for unsampled internal handlers and enrichment is shown only where documented.

Main entry points: [`internal/risk/service.go`](https://github.com/vmcchooky/safe-zone/blob/main/internal/risk/service.go) (Risk policy), [`internal/dns/resolver/resolver.go`](https://github.com/vmcchooky/safe-zone/blob/main/internal/dns/resolver/resolver.go) (DNS policy), [`cmd/core-api/main.go`](https://github.com/vmcchooky/safe-zone/blob/main/cmd/core-api/main.go) (Core API), [`internal/api/handlers/handler.go`](https://github.com/vmcchooky/safe-zone/blob/main/internal/api/handlers/handler.go) (Operator handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dns["DNS protection"]
  node_resolver_app["DNS resolver<br/>[main.go]"]
  node_dns_router["DNS router<br/>[router.go]"]
  node_resolver["DNS policy<br/>[resolver.go]"]
  node_doh["DoH service<br/>[server.go]"]
  node_upstream["Upstream DNS<br/>[upstream.go]"]
end

subgraph group_decision["Verdict engine"]
  node_analysis["Domain analysis<br/>[analysis.go]"]
  node_risk["Risk policy<br/>[service.go]"]
  node_ml["ML classifier<br/>[ml_classifier.go]"]
  node_ai["AI provider<br/>[provider.go]"]
end

subgraph group_operations["Operator control"]
  node_core["Core API<br/>[main.go]"]
  node_api_router["API router<br/>[router.go]"]
  node_handlers["Operator handlers<br/>[handler.go]"]
  node_dashboard["Operator dashboard<br/>[App.tsx]"]
  node_ui_api["Dashboard API client<br/>[api.ts]"]
end

subgraph group_state["State and intel"]
  node_feed_sync["Feed synchronization<br/>[sync.go]"]
  node_feed_data[("Threat feeds<br/>[admission.go]")]
  node_store[("SQLite storage<br/>[sqlite.go]")]
  node_redis[("Redis cache<br/>[redis.go]")]
end

subgraph group_agents["Automation"]
  node_agent_engine["Agent scheduler<br/>[engine.go]"]
  node_agent_tasks["Agent tasks<br/>[feedsync.go]"]
  node_osint["OSINT enrichment<br/>[osint.go]"]
end

node_client(("DNS client"))
node_external_dns(("DNS upstream"))
node_feed_sources(("Threat feed sources"))

node_client -->|"sends DNS query"| node_resolver_app
node_resolver_app -->|"serves requests"| node_dns_router
node_dns_router -->|"dispatches query"| node_resolver
node_resolver -->|"requests verdict"| node_risk
node_risk -->|"scores domain"| node_analysis
node_analysis -.->|"classifies optionally"| node_ml
node_risk -.->|"refines optionally"| node_ai
node_resolver -->|"serves DoH"| node_doh
node_doh -->|"resolves allowed query"| node_upstream
node_upstream -->|"forwards query"| node_external_dns
node_core -->|"starts API"| node_api_router
node_api_router -->|"dispatches requests"| node_handlers
node_dashboard -->|"uses API client"| node_ui_api
node_ui_api -->|"calls API"| node_core
node_handlers -->|"analyzes domains"| node_risk
node_handlers -->|"reads and writes"| node_store
node_risk -->|"caches verdicts"| node_redis
node_feed_sync -->|"fetches feeds"| node_feed_sources
node_feed_sync -->|"admits feed entries"| node_feed_data
node_risk -->|"matches feed entries"| node_feed_data
node_core -->|"starts scheduler"| node_agent_engine
node_agent_engine -->|"runs tasks"| node_agent_tasks
node_agent_tasks -->|"synchronizes feeds"| node_feed_sync
node_agent_tasks -->|"runs enrichment"| node_osint
node_osint -->|"provides evidence"| node_risk

click node_resolver_app "https://github.com/vmcchooky/safe-zone/blob/main/cmd/dns-resolver/main.go"
click node_dns_router "https://github.com/vmcchooky/safe-zone/blob/main/internal/dns/server/router.go"
click node_resolver "https://github.com/vmcchooky/safe-zone/blob/main/internal/dns/resolver/resolver.go"
click node_doh "https://github.com/vmcchooky/safe-zone/blob/main/internal/dns/doh/server.go"
click node_upstream "https://github.com/vmcchooky/safe-zone/blob/main/internal/dns/doh/upstream.go"
click node_core "https://github.com/vmcchooky/safe-zone/blob/main/cmd/core-api/main.go"
click node_api_router "https://github.com/vmcchooky/safe-zone/blob/main/internal/api/server/router.go"
click node_handlers "https://github.com/vmcchooky/safe-zone/blob/main/internal/api/handlers/handler.go"
click node_dashboard "https://github.com/vmcchooky/safe-zone/blob/main/ui/src/App.tsx"
click node_ui_api "https://github.com/vmcchooky/safe-zone/blob/main/ui/src/lib/api.ts"
click node_analysis "https://github.com/vmcchooky/safe-zone/blob/main/internal/analysis/analysis.go"
click node_risk "https://github.com/vmcchooky/safe-zone/blob/main/internal/risk/service.go"
click node_ml "https://github.com/vmcchooky/safe-zone/blob/main/internal/analysis/ml_classifier.go"
click node_ai "https://github.com/vmcchooky/safe-zone/blob/main/internal/ai/provider.go"
click node_feed_sync "https://github.com/vmcchooky/safe-zone/blob/main/internal/feed/sync.go"
click node_feed_data "https://github.com/vmcchooky/safe-zone/blob/main/internal/feed/admission.go"
click node_store "https://github.com/vmcchooky/safe-zone/blob/main/internal/store/sqlite.go"
click node_redis "https://github.com/vmcchooky/safe-zone/blob/main/internal/cache/redis.go"
click node_agent_engine "https://github.com/vmcchooky/safe-zone/blob/main/internal/agent/engine.go"
click node_agent_tasks "https://github.com/vmcchooky/safe-zone/blob/main/internal/agent/feedsync.go"
click node_osint "https://github.com/vmcchooky/safe-zone/blob/main/internal/agent/osint.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_resolver_app,node_dns_router,node_resolver,node_doh,node_upstream,node_client toneBlue
class node_analysis,node_risk,node_ml,node_ai toneAmber
class node_core,node_api_router,node_handlers,node_dashboard,node_ui_api toneMint
class node_feed_sync,node_feed_data,node_store,node_redis toneRose
class node_agent_engine,node_agent_tasks,node_osint,node_external_dns,node_feed_sources toneIndigo
```

## Components

### DNS protection

- [DNS resolver](https://github.com/vmcchooky/safe-zone/blob/main/cmd/dns-resolver/main.go): `cmd/dns-resolver/main.go`
- [DNS router](https://github.com/vmcchooky/safe-zone/blob/main/internal/dns/server/router.go): `internal/dns/server/router.go`
- [DNS policy](https://github.com/vmcchooky/safe-zone/blob/main/internal/dns/resolver/resolver.go): `internal/dns/resolver/resolver.go`
- [DoH service](https://github.com/vmcchooky/safe-zone/blob/main/internal/dns/doh/server.go): `internal/dns/doh/server.go`
- [Upstream DNS](https://github.com/vmcchooky/safe-zone/blob/main/internal/dns/doh/upstream.go): `internal/dns/doh/upstream.go`

### Verdict engine

- [Domain analysis](https://github.com/vmcchooky/safe-zone/blob/main/internal/analysis/analysis.go): `internal/analysis/analysis.go`
- [Risk policy](https://github.com/vmcchooky/safe-zone/blob/main/internal/risk/service.go): `internal/risk/service.go`
- [ML classifier](https://github.com/vmcchooky/safe-zone/blob/main/internal/analysis/ml_classifier.go): `internal/analysis/ml_classifier.go`
- [AI provider](https://github.com/vmcchooky/safe-zone/blob/main/internal/ai/provider.go): `internal/ai/provider.go`

### Operator control

- [Core API](https://github.com/vmcchooky/safe-zone/blob/main/cmd/core-api/main.go): `cmd/core-api/main.go`
- [API router](https://github.com/vmcchooky/safe-zone/blob/main/internal/api/server/router.go): `internal/api/server/router.go`
- [Operator handlers](https://github.com/vmcchooky/safe-zone/blob/main/internal/api/handlers/handler.go): `internal/api/handlers/handler.go`
- [Operator dashboard](https://github.com/vmcchooky/safe-zone/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [Dashboard API client](https://github.com/vmcchooky/safe-zone/blob/main/ui/src/lib/api.ts): `ui/src/lib/api.ts`

### State and intel

- [Feed synchronization](https://github.com/vmcchooky/safe-zone/blob/main/internal/feed/sync.go): `internal/feed/sync.go`
- [Threat feeds](https://github.com/vmcchooky/safe-zone/blob/main/internal/feed/admission.go): `internal/feed/admission.go`
- [SQLite storage](https://github.com/vmcchooky/safe-zone/blob/main/internal/store/sqlite.go): `internal/store/sqlite.go`
- [Redis cache](https://github.com/vmcchooky/safe-zone/blob/main/internal/cache/redis.go): `internal/cache/redis.go`

### Automation

- [Agent scheduler](https://github.com/vmcchooky/safe-zone/blob/main/internal/agent/engine.go): `internal/agent/engine.go`
- [Agent tasks](https://github.com/vmcchooky/safe-zone/blob/main/internal/agent/feedsync.go): `internal/agent/feedsync.go`
- [OSINT enrichment](https://github.com/vmcchooky/safe-zone/blob/main/internal/agent/osint.go): `internal/agent/osint.go`

### Other components

- **DNS client**
- **DNS upstream**
- **Threat feed sources**

## Connections

- DNS client → DNS resolver: sends DNS query
- DNS resolver → DNS router: serves requests
- DNS router → DNS policy: dispatches query
- DNS policy → Risk policy: requests verdict
- Risk policy → Domain analysis: scores domain
- Domain analysis → ML classifier: classifies optionally
- Risk policy → AI provider: refines optionally
- DNS policy → DoH service: serves DoH
- DoH service → Upstream DNS: resolves allowed query
- Upstream DNS → DNS upstream: forwards query
- Core API → API router: starts API
- API router → Operator handlers: dispatches requests
- Operator dashboard → Dashboard API client: uses API client
- Dashboard API client → Core API: calls API
- Operator handlers → Risk policy: analyzes domains
- Operator handlers → SQLite storage: reads and writes
- Risk policy → Redis cache: caches verdicts
- Feed synchronization → Threat feed sources: fetches feeds
- Feed synchronization → Threat feeds: admits feed entries
- Risk policy → Threat feeds: matches feed entries
- Core API → Agent scheduler: starts scheduler
- Agent scheduler → Agent tasks: runs tasks
- Agent tasks → Feed synchronization: synchronizes feeds
- Agent tasks → OSINT enrichment: runs enrichment
- OSINT enrichment → Risk policy: provides evidence