# silfius/auditor-ips architecture

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

- Interactive diagram: https://gitdiagram.com/silfius/auditor-ips
- Repository: https://github.com/silfius/auditor-ips

## Overview

1. **System shape**
   - Auditor IPs is a **self-hosted Python web application** for **private LAN monitoring**.
   - The repo is organized as a **single backend service** that serves both **HTML pages** and a **JSON API**, packaged for **Docker/Docker Compose** deployment.

2. **Bootstrap and runtime lifecycle**
   - `app/main.py` is the main application entrypoint.
   - `app/config.py`, `app/database.py`, and `app/check_startup.py` handle environment-driven configuration, persistence setup, and startup validation.
   - `app/entrypoint.sh` and `app/dockerfile` define container startup behavior; the app is expected to run inside a managed container rather than as scattered system services.

3. **Persistence boundary**
   - The backend has a central **database layer** in `app/database.py`.
   - Operational data such as hosts, scans, alerts, service status, quality metrics, and configuration state are stored there.
   - The repo also implies a **filesystem boundary** for exports, reports, logs, and deployment artifacts via `docker-compose.yml.example`, `SNAPSHOT_MANIFEST.json`, and the docs around backup/restore.

4. **Network discovery and inventory pipeline**
   - Discovery is a dedicated subsystem: `app/scan_discovery.py`, `app/scan_scheduler.py`, and `app/routers/discovery.py`.
   - It appears to periodically discover LAN hosts, then feed results into inventory and status views.
   - This is the core data flow: **network scan → parsed host facts → persisted inventory → UI/API consumption**.

5. **Enrichment and classification pipeline**
   - `app/device_enrichment.py`, `app/scan_enrichment_runners.py`, `app/fingerprint_utils.py`, and `app/host_classification.py` indicate a second-stage pipeline after discovery.
   - Hosts are enriched with device metadata, fingerprinted, and classified into types or roles.
   - This likely turns raw scan results into more useful operational views like “known host”, “service host”, or other category labels.

6. **Domain API/router structure**
   - The `app/routers/` package splits the backend into domains:
     - `hosts`, `scans`, `services`, `alerts`, `quality`
     - `daily_report`, `export_scheduler`, `config_api`
     - `system_health`, `scripts_status`, `syncthing_control`
     - `auth`, `router_ssh`
   - This suggests a **modular API boundary** where each router owns one functional area rather than a monolithic endpoint layer.

7. **Authentication and request protection**
   - `app/auth_middleware.py` and `app/routers/auth.py` form the access-control layer.
   - The presence of `app/templates/login.html` indicates user login is part of the system, not just API tokens.
   - Protected API routes and internal dashboards are likely gated by middleware/session logic.

8. **Frontend delivery**
   - Server-rendered templates live in `app/templates/`, while client behavior is in `app/static/js/`.
   - The UI is split into page-specific scripts for dashboard, hosts, scans, services, alerts, quality, config, auth, Syncthing control, and export configuration.
   - `app/sw.js` suggests a service worker for limited offline/cache behavior or improved loading, but the app is still fundamentally a browser-based admin console.

9. **External integrations**
   - `app/routers/syncthing_control.py` shows an integration with **Syncthing Control** in **read-only mode**.
   - `app/routers/router_ssh.py` suggests SSH-based interaction for controlled remote operations or status checks.
   - `app/routers/services.py` and `app/routers/scripts_status.py` indicate the app also observes internal automation or service processes, not just network devices.

10. **Operational visibility and reporting**
   - `app/routers/system_health.py` provides health endpoints, and the README highlights `/api/system/healthz` plus `scripts/smoke_system_health.sh`.
   - `app/routers/daily_report.py` and `app/routers/export_scheduler.py` suggest scheduled reporting and export generation.
   - `app/routers/alerts.py` and `app/routers/quality.py` represent operational feedback loops: detect issues, store them, and present them in the dashboard.

11. **Deployment and support tooling**
   - Deployment is intended through **Docker Compose** on Linux with writable data paths.
   - `scripts/install_auditor.py` automates installation and setup, while the docs cover install, configuration, backup/restore, upgrade, and security.
   - The architecture is therefore closer to an **appliance-like self-hosted service** than a library or distributed microservice system.

12. **How to draw the architecture**
   - Put the **Python backend container** at the center.
   - On the left, show **persistent storage**: database plus filesystem for exports/config/logs.
   - On the right, show **LAN hosts/devices**, **Syncthing Control**, and any **SSH-managed targets** as external systems.
   - At the top, show the **browser UI** using templates and static JS.
   - At the bottom, show **Docker/Compose and host OS** as the deployment layer, with schedulers running inside the backend for discovery, enrichment, reports, and health checks.

Main entry points: [`app/main.py`](https://github.com/silfius/auditor-ips/blob/main/app/main.py) (App entry), [`app/database.py`](https://github.com/silfius/auditor-ips/blob/main/app/database.py) (Database), [`app/device_enrichment.py`](https://github.com/silfius/auditor-ips/blob/main/app/device_enrichment.py) (Device enrichment), [`app/routers/syncthing_control.py`](https://github.com/silfius/auditor-ips/blob/main/app/routers/syncthing_control.py) (Sync/SSH control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_docker["Docker/Compose<br/>deployment"]
  node_installer["Install script<br/>ops tooling<br/>[install_auditor.py]"]
end

subgraph group_backend["Backend Service"]
  node_main["App entry<br/>ASGI app<br/>[main.py]"]
  node_config["Config<br/>[config.py]"]
  node_startup["Startup checks<br/>validation<br/>[check_startup.py]"]
  node_authmw["Auth middleware<br/>access control<br/>[auth_middleware.py]"]
  node_hosts_api["Hosts<br/>router<br/>[hosts.py]"]
  node_scans_api["Scans<br/>router<br/>[scans.py]"]
  node_services_api["Services<br/>router<br/>[services.py]"]
  node_alerts_api["Alerts<br/>router<br/>[alerts.py]"]
  node_quality_api["Quality<br/>router<br/>[quality.py]"]
  node_reporting["Reports<br/>scheduler router<br/>[daily_report.py]"]
  node_system_api["System health<br/>health router<br/>[system_health.py]"]
  node_sync_ssh["Sync/SSH control<br/>integration router"]
  node_auth_api["Auth<br/>router<br/>[auth.py]"]
end

subgraph group_pipeline["Discovery Pipeline"]
  node_scan_discovery["Discovery<br/>scan service<br/>[scan_discovery.py]"]
  node_scan_sched["Scan scheduler<br/>[scan_scheduler.py]"]
  node_enrich_runners["Enrichment runners<br/>pipeline jobs"]
  node_device_enrich["Device enrichment<br/>metadata enrichment"]
  node_fingerprint["Fingerprinting<br/>feature extraction"]
  node_classification["Classification<br/>host tagging"]
end

subgraph group_external["External Systems"]
  node_browser(("Browser admin<br/>operator UI"))
  node_lan{{"LAN devices<br/>network targets"}}
  node_syncthing{{"Syncthing<br/>external integration"}}
  node_ssh_targets{{"SSH targets<br/>remote systems"}}
end

subgraph group_storage["Persistence"]
  node_database[("Database<br/>persistence layer<br/>[database.py]")]
  node_filesystem["Files and exports<br/>artifact store"]
end

subgraph group_ui["Browser UI"]
  node_templates["Templates<br/>server views<br/>[index.html]"]
  node_static_js["Client JS<br/>frontend scripts<br/>[app.js]"]
  node_sw["Service worker<br/>browser cache<br/>[sw.js]"]
end

node_docker -->|"runs"| node_main
node_installer -->|"sets up"| node_docker
node_main -->|"loads"| node_config
node_main -->|"validates"| node_startup
node_main -->|"enforces"| node_authmw
node_main -->|"uses"| node_database
node_main -->|"serves"| node_templates
node_main -->|"mounts"| node_hosts_api
node_main -->|"mounts"| node_scans_api
node_main -->|"mounts"| node_services_api
node_main -->|"mounts"| node_alerts_api
node_main -->|"mounts"| node_quality_api
node_main -->|"mounts"| node_reporting
node_main -->|"mounts"| node_system_api
node_main -->|"mounts"| node_sync_ssh
node_main -->|"mounts"| node_auth_api
node_scan_sched -->|"triggers"| node_scan_discovery
node_scan_discovery -->|"scans"| node_lan
node_scan_discovery -->|"stores"| node_database
node_enrich_runners -->|"runs"| node_device_enrich
node_device_enrich -->|"uses"| node_fingerprint
node_device_enrich -->|"feeds"| node_classification
node_device_enrich -->|"updates"| node_database
node_hosts_api -->|"reads/writes"| node_database
node_scans_api -->|"reads"| node_database
node_services_api -->|"reads"| node_database
node_alerts_api -->|"reads/writes"| node_database
node_quality_api -->|"reads/writes"| node_database
node_reporting -->|"reads"| node_database
node_reporting -->|"writes"| node_filesystem
node_system_api -->|"reads"| node_database
node_sync_ssh -->|"controls"| node_syncthing
node_sync_ssh -->|"queries"| node_ssh_targets
node_templates -->|"loads"| node_static_js
node_static_js -->|"runs in"| node_browser
node_sw -->|"caches"| node_browser
node_browser -->|"logs in"| node_auth_api
node_browser -->|"views"| node_hosts_api
node_browser -->|"views"| node_scans_api
node_browser -->|"views"| node_alerts_api
node_browser -->|"views"| node_quality_api
node_browser -->|"checks"| node_system_api
node_browser -->|"operates"| node_sync_ssh
node_filesystem -.->|"backs"| node_database

click node_main "https://github.com/silfius/auditor-ips/blob/main/app/main.py"
click node_config "https://github.com/silfius/auditor-ips/blob/main/app/config.py"
click node_startup "https://github.com/silfius/auditor-ips/blob/main/app/check_startup.py"
click node_authmw "https://github.com/silfius/auditor-ips/blob/main/app/auth_middleware.py"
click node_database "https://github.com/silfius/auditor-ips/blob/main/app/database.py"
click node_scan_discovery "https://github.com/silfius/auditor-ips/blob/main/app/scan_discovery.py"
click node_scan_sched "https://github.com/silfius/auditor-ips/blob/main/app/scan_scheduler.py"
click node_enrich_runners "https://github.com/silfius/auditor-ips/blob/main/app/scan_enrichment_runners.py"
click node_device_enrich "https://github.com/silfius/auditor-ips/blob/main/app/device_enrichment.py"
click node_fingerprint "https://github.com/silfius/auditor-ips/blob/main/app/fingerprint_utils.py"
click node_classification "https://github.com/silfius/auditor-ips/blob/main/app/host_classification.py"
click node_hosts_api "https://github.com/silfius/auditor-ips/blob/main/app/routers/hosts.py"
click node_scans_api "https://github.com/silfius/auditor-ips/blob/main/app/routers/scans.py"
click node_services_api "https://github.com/silfius/auditor-ips/blob/main/app/routers/services.py"
click node_alerts_api "https://github.com/silfius/auditor-ips/blob/main/app/routers/alerts.py"
click node_quality_api "https://github.com/silfius/auditor-ips/blob/main/app/routers/quality.py"
click node_reporting "https://github.com/silfius/auditor-ips/blob/main/app/routers/daily_report.py"
click node_system_api "https://github.com/silfius/auditor-ips/blob/main/app/routers/system_health.py"
click node_sync_ssh "https://github.com/silfius/auditor-ips/blob/main/app/routers/syncthing_control.py"
click node_auth_api "https://github.com/silfius/auditor-ips/blob/main/app/routers/auth.py"
click node_templates "https://github.com/silfius/auditor-ips/blob/main/app/templates/index.html"
click node_static_js "https://github.com/silfius/auditor-ips/blob/main/app/static/js/app.js"
click node_sw "https://github.com/silfius/auditor-ips/blob/main/app/sw.js"
click node_docker "https://github.com/silfius/auditor-ips/blob/main/docker-compose.yml.example"
click node_installer "https://github.com/silfius/auditor-ips/blob/main/scripts/install_auditor.py"
click node_filesystem "https://github.com/silfius/auditor-ips/blob/main/SNAPSHOT_MANIFEST.json"

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_docker,node_installer toneBlue
class node_main,node_config,node_startup,node_authmw,node_hosts_api,node_scans_api,node_services_api,node_alerts_api,node_quality_api,node_reporting,node_system_api,node_sync_ssh,node_auth_api toneAmber
class node_scan_discovery,node_scan_sched,node_enrich_runners,node_device_enrich,node_fingerprint,node_classification toneMint
class node_browser,node_lan,node_syncthing,node_ssh_targets toneRose
class node_database,node_filesystem toneIndigo
class node_templates,node_static_js,node_sw toneTeal
```

## Components

### Deployment

Containerized runtime and install/compose layer

- [Docker/Compose](https://github.com/silfius/auditor-ips/blob/main/docker-compose.yml.example): deployment · Container and compose deployment layer · `docker-compose.yml.example`
- [Install script](https://github.com/silfius/auditor-ips/blob/main/scripts/install_auditor.py): ops tooling · Automated installation and setup helper · `scripts/install_auditor.py`

### Backend Service

Single Python service that serves UI and API

- [App entry](https://github.com/silfius/auditor-ips/blob/main/app/main.py): ASGI app · Main application entrypoint · `app/main.py`
- [Config](https://github.com/silfius/auditor-ips/blob/main/app/config.py): env config · Environment-driven application settings · `app/config.py`
- [Startup checks](https://github.com/silfius/auditor-ips/blob/main/app/check_startup.py): validation · Preflight validation and readiness checks · `app/check_startup.py`
- [Auth middleware](https://github.com/silfius/auditor-ips/blob/main/app/auth_middleware.py): access control · Request protection for UI and API routes · `app/auth_middleware.py`
- [Hosts](https://github.com/silfius/auditor-ips/blob/main/app/routers/hosts.py): router · Host inventory and detail views · `app/routers/hosts.py`
- [Scans](https://github.com/silfius/auditor-ips/blob/main/app/routers/scans.py): router · Scan history and discovery results · `app/routers/scans.py`
- [Services](https://github.com/silfius/auditor-ips/blob/main/app/routers/services.py): router · Service status and operational views · `app/routers/services.py`
- [Alerts](https://github.com/silfius/auditor-ips/blob/main/app/routers/alerts.py): router · Alert storage and dashboard views · `app/routers/alerts.py`
- [Quality](https://github.com/silfius/auditor-ips/blob/main/app/routers/quality.py): router · Data quality and integrity views · `app/routers/quality.py`
- [Reports](https://github.com/silfius/auditor-ips/blob/main/app/routers/daily_report.py): scheduler router · Daily reporting and export scheduling · `app/routers/daily_report.py`
- [System health](https://github.com/silfius/auditor-ips/blob/main/app/routers/system_health.py): health router · Health and readiness endpoints · `app/routers/system_health.py`
- [Sync/SSH control](https://github.com/silfius/auditor-ips/blob/main/app/routers/syncthing_control.py): integration router · Syncthing read-only control and SSH-based operations · `app/routers/syncthing_control.py`
- [Auth](https://github.com/silfius/auditor-ips/blob/main/app/routers/auth.py): router · Login and session access flows · `app/routers/auth.py`

### Discovery Pipeline

Scan, enrichment, and classification flow

- [Discovery](https://github.com/silfius/auditor-ips/blob/main/app/scan_discovery.py): scan service · LAN host discovery and scan parsing · `app/scan_discovery.py`
- [Scan scheduler](https://github.com/silfius/auditor-ips/blob/main/app/scan_scheduler.py): scheduler · Periodic scan orchestration · `app/scan_scheduler.py`
- [Enrichment runners](https://github.com/silfius/auditor-ips/blob/main/app/scan_enrichment_runners.py): pipeline jobs · Runs post-scan enrichment tasks · `app/scan_enrichment_runners.py`
- [Device enrichment](https://github.com/silfius/auditor-ips/blob/main/app/device_enrichment.py): metadata enrichment · Adds device metadata to discovered hosts · `app/device_enrichment.py`
- [Fingerprinting](https://github.com/silfius/auditor-ips/blob/main/app/fingerprint_utils.py): feature extraction · Host fingerprint utilities for identification · `app/fingerprint_utils.py`
- [Classification](https://github.com/silfius/auditor-ips/blob/main/app/host_classification.py): host tagging · Assigns host type or role labels · `app/host_classification.py`

### External Systems

LAN devices and managed integrations

- **Browser admin**: operator UI · Human-facing dashboard and login experience
- **LAN devices**: network targets · Discovered hosts and devices on the local network
- **Syncthing**: external integration · Read-only Syncthing control target
- **SSH targets**: remote systems · Systems reached through SSH-based control or checks

### Persistence

Database and filesystem-backed operational state

- [Database](https://github.com/silfius/auditor-ips/blob/main/app/database.py): persistence layer · Central storage for hosts, scans, alerts, quality, and config state · `app/database.py`
- [Files and exports](https://github.com/silfius/auditor-ips/blob/main/SNAPSHOT_MANIFEST.json): artifact store · Writable filesystem for reports, exports, logs, and snapshots · `SNAPSHOT_MANIFEST.json`

### Browser UI

Server-rendered pages and client scripts

- [Templates](https://github.com/silfius/auditor-ips/blob/main/app/templates/index.html): server views · HTML pages rendered by the backend · `app/templates/index.html`
- [Client JS](https://github.com/silfius/auditor-ips/blob/main/app/static/js/app.js): frontend scripts · Page-specific browser behavior · `app/static/js/app.js`
- [Service worker](https://github.com/silfius/auditor-ips/blob/main/app/sw.js): browser cache · Client-side caching and load assistance · `app/sw.js`

## Connections

- Docker/Compose → App entry: runs · Compose starts the application container
- Install script → Docker/Compose: sets up · Installer prepares the deployment environment
- App entry → Config: loads · Application bootstraps from environment configuration
- App entry → Startup checks: validates · Performs startup checks before serving traffic
- App entry → Auth middleware: enforces · Installs request protection around routes
- App entry → Database: uses · Connects the app to persistent state
- App entry → Templates: serves · Renders HTML pages for the browser UI
- App entry → Hosts: mounts · Exposes host domain endpoints
- App entry → Scans: mounts · Exposes scan domain endpoints
- App entry → Services: mounts · Exposes service status endpoints
- App entry → Alerts: mounts · Exposes alert endpoints
- App entry → Quality: mounts · Exposes quality endpoints
- App entry → Reports: mounts · Exposes reporting and export scheduling
- App entry → System health: mounts · Exposes health endpoints
- App entry → Sync/SSH control: mounts · Exposes integration control endpoints
- App entry → Auth: mounts · Exposes authentication endpoints
- Scan scheduler → Discovery: triggers · Schedules periodic discovery runs
- Discovery → LAN devices: scans · Discovers hosts on the local network
- Discovery → Database: stores · Persists discovered inventory and scan results
- Enrichment runners → Device enrichment: runs · Executes metadata enrichment jobs
- Device enrichment → Fingerprinting: uses · Derives identity signals for hosts
- Device enrichment → Classification: feeds · Turns fingerprints into host categories
- Device enrichment → Database: updates · Writes enriched host state back to persistence
- Hosts → Database: reads/writes · Serves inventory data from persistence
- Scans → Database: reads · Shows scan history and discovery state
- Services → Database: reads · Reads service status and process state
- Alerts → Database: reads/writes · Stores and presents alert data
- Quality → Database: reads/writes · Tracks data quality metrics
- Reports → Database: reads · Builds reports and exports from stored state
- Reports → Files and exports: writes · Generates reports and export artifacts
- System health → Database: reads · Reports backend health and readiness
- Sync/SSH control → Syncthing: controls · Integrates with Syncthing in read-only mode
- Sync/SSH control → SSH targets: queries · Uses SSH-based access for controlled operations
- Templates → Client JS: loads · Pages are enhanced by browser scripts
- Client JS → Browser admin: runs in · Client-side behavior executes in the browser
- Service worker → Browser admin: caches · Provides browser caching and load assistance
- Browser admin → Auth: logs in · Users authenticate through the login flow
- Browser admin → Hosts: views · Operator dashboard consumes host data
- Browser admin → Scans: views · Operator dashboard consumes scan data
- Browser admin → Alerts: views · Operator dashboard consumes alert data
- Browser admin → Quality: views · Operator dashboard consumes quality data
- Browser admin → System health: checks · Browser or probes can verify health endpoints
- Browser admin → Sync/SSH control: operates · Admin UI can drive integration controls
- Files and exports → Database: backs · Operational files complement persisted state
