# noph8/dnh architecture

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

- Interactive diagram: https://gitdiagram.com/noph8/dnh
- Repository: https://github.com/noph8/dnh

## Overview

##### Project type and purpose
- This is a monolithic full-stack web application built with Flask.
- Purpose: a VPN routing helper (“dnh”) that lets admins register domain names and IP-ranges via a web UI (Flask-Admin) and exposes a REST API endpoint to fetch the consolidated list for VPN routing.
- It also runs a periodic scheduler to refresh DNS lookups of domain names against configured DNS servers.

##### High-level components
a. Clients
- Admin user’s browser (Web UI)
- API consumer (e.g., router or script calling `/api/v1/ip_list`)
b. Backend
- Flask application (app/) organized into:
– Blueprints: `app/api` for REST API; `app/dashboard.py` + templates/static for Admin UI
– Models: `app/models.py` (SQLAlchemy ORM)
– Management commands: `app/management.py` (e.g., `createsuperuser`)
– Scheduler/tasks: `app/scheduler.py`, `app/tasks.py` to periodically resolve domains
– Utilities: `app/tools/*` (network, datetime, JSON helpers)
- Configuration: `config.py` + environment variables (.env.template)
c. Data store
- SQLite database (file specified by DB_PATH/DB_NAME)
d. External services
- Upstream DNS servers (configured via DNS_SERVERS)
- Deployment target (Docker container via Dockerfile/docker-compose)
- Optional: OpenWRT/WireGuard router consuming the API

##### Interactions and data flow
1. Admin logs into Web UI → Flask renders templates (app/templates) → Admin creates/edits domain and IP-range records → writes to SQLite
2. Scheduler (via APScheduler or RQ) wakes every `DNS_UPDATE_INTERVAL` → tasks use `app/tools/network` to query DNS servers → updates records/timestamps in DB
3. API client calls `/api/v1/ip_list?api_key=` → request hits Flask API blueprint → validators check API key → views query DB → response serialized (app/formatters, app/api/v1/validators) → JSON list returned
4. Dockerized deployment: Dockerfile builds image; `docker-compose.yml` sets up container with .env, mounts volume for DB

##### Architectural patterns & design principles
- MVC / Blueprint separation:
- Models in `app/models.py`
- Views & controllers in `app/api/*` and `app/dashboard.py`
- Templates & static assets under `app/templates` + `app/static`
- Layered services: data layer (SQLite), business logic (tasks, formatters), presentation (templates/API responses)
- Config-over-code: all behavior driven by environment variables via `config.py`
- Modular utilities: `app/tools` for cross-cutting concerns

- Call out the main frameworks/libs: “Flask + Flask-Security”, “SQLite”, “APScheduler (or RQ)”.
- Docker boundary and the mounting of the DB file and .env.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External Clients"
        direction TB
        Browser["Admin Browser"]:::external
        APIClient["API Client (Router/Script)"]:::external
        DNSServer["DNS Servers"]:::external
    end

    %% Docker Container Boundary
    subgraph Docker["Docker Container"]
        direction TB

        %% Configuration
        subgraph "Configuration"
            Env[".env / config.py"]:::config
        end

        %% Flask Application Modules
        subgraph "Flask Application"
            direction TB
            AdminUI["Admin UI Module\n(Flask-Admin)"]:::app
            API["API Module"]:::app
            Scheduler["Scheduler / Tasks"]:::app
            Utils["Utilities / Tools"]:::app
            Formatters["Request/Response Formatters"]:::app
            Models["Models\n(SQLAlchemy)"]:::app
            DBInit["Database Initialization"]:::app
            Mgmt["Management Commands"]:::app
        end

        %% Data Store
        Database["SQLite Database"]:::database
    end

    %% Interactions
    Browser -->|"HTTP request\n(Admin UI)"| AdminUI
    AdminUI -->|"SQL read/write"| Database

    APIClient -->|"HTTP request\n(API)"| API
    API -->|"SQL read"| Database
    Database -->|"SQL results"| API
    API -->|"HTTP response\n(JSON)"| APIClient

    Scheduler -->|"DNS query"| DNSServer
    DNSServer -->|"DNS response"| Scheduler
    Scheduler -->|"SQL write/update"| Database

    Env -->|"Environment Variables"| AdminUI
    Env -->|"Environment Variables"| API
    Env -->|"Environment Variables"| Scheduler

    %% Docker Container Style
    style Docker stroke:#333,stroke-dasharray:5 5

    %% Click Events
    click AdminUI "https://github.com/noph8/dnh/blob/master/app/dashboard.py"
    click API "https://github.com/noph8/dnh/tree/master/app/api/"
    click Scheduler "https://github.com/noph8/dnh/blob/master/app/scheduler.py"
    click Utils "https://github.com/noph8/dnh/blob/master/app/tools/utils.py"
    click Formatters "https://github.com/noph8/dnh/blob/master/app/formatters.py"
    click Models "https://github.com/noph8/dnh/blob/master/app/models.py"
    click DBInit "https://github.com/noph8/dnh/blob/master/app/database.py"
    click Mgmt "https://github.com/noph8/dnh/blob/master/app/management.py"
    click Env "https://github.com/noph8/dnh/blob/master/config.py"

    %% Styles
    classDef external fill:#d0ebff,stroke:#1e90ff
    classDef app fill:#d4f8d4,stroke:#2e8b57
    classDef database fill:#ffe4b5,stroke:#ff8c00
    classDef config fill:#e0e0ff,stroke:#6a5acd
```
