# spatiumnorth/spatiumddi architecture

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

- Interactive diagram: https://gitdiagram.com/spatiumnorth/spatiumddi
- Repository: https://github.com/spatiumnorth/spatiumddi

## Overview

SpatiumDDI is a self-hosted DNS, DHCP, and IPAM control plane that manages real DNS/DHCP servers. The principal workflow is an operator managing network address and service data through the API, with the control plane coordinating configuration to agents and runtime services. The tree also shows appliance management, BGP looking-glass ingestion, search, and conformity evaluation. README claims support for integrated DNS/DHCP containers; sampled excerpts are partial and do not establish all cross-module call paths, so uncertain wiring is omitted.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/router.py) (REST API), [`backend/app/api/v1/appliance/router.py`](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/appliance/router.py) (Appliance management), [`agent/supervisor/spatium_supervisor/service_lifecycle.py`](https://github.com/spatiumnorth/spatiumddi/blob/main/agent/supervisor/spatium_supervisor/service_lifecycle.py) (Appliance supervisor), [`backend/app/services/looking_glass/routes_ingest.py`](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/looking_glass/routes_ingest.py) (Route ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_api["REST API<br/>[router.py]"]
  node_search["Global search<br/>[engine.py]"]
  node_database[("Application database<br/>[db.py]")]
end

subgraph group_ddi["DDI services"]
  node_ipam["IP address management<br/>[router.py]"]
  node_dns_api["DNS management<br/>[router.py]"]
  node_dhcp_api["DHCP management<br/>[scopes.py]"]
  node_dns_import["DNS import<br/>[router.py]"]
  node_dhcp_import["DHCP import<br/>[router.py]"]
end

subgraph group_agents["Agent runtime"]
  node_dns_agent["DNS agent<br/>[sync.py]"]
  node_dhcp_agent["DHCP agent<br/>[sync.py]"]
  node_dns_drivers["DNS server drivers<br/>[base.py]"]
  node_dhcp_drivers["DHCP server drivers<br/>[base.py]"]
  node_lg_agents["Looking-glass agents<br/>[agents.py]"]
  node_route_ingest["Route ingestion<br/>[routes_ingest.py]"]
  node_supervisor["Appliance supervisor"]
end

subgraph group_operations["Operations"]
  node_appliance_api["Appliance management<br/>[router.py]"]
  node_storage_actions["Storage actions<br/>[storage_actions.py]"]
  node_storage_health["Storage health<br/>[storage_health.py]"]
  node_conformity["Conformity evaluation<br/>[engine.py]"]
end

node_operator(("Operator"))
node_dns_servers{{"DNS servers"}}
node_dhcp_servers{{"DHCP servers"}}

node_operator -->|"submits requests"| node_api
node_api -->|"dispatches"| node_ipam
node_api -->|"dispatches"| node_dns_api
node_api -->|"dispatches"| node_dhcp_api
node_api -->|"dispatches"| node_dns_import
node_api -->|"dispatches"| node_dhcp_import
node_dns_agent -->|"applies configuration"| node_dns_servers
node_dhcp_agent -->|"applies configuration"| node_dhcp_servers
node_dns_drivers -->|"controls"| node_dns_servers
node_dhcp_drivers -->|"controls"| node_dhcp_servers
node_lg_agents -->|"pushes routes"| node_route_ingest
node_route_ingest -->|"reconciles routes"| node_database
node_api -->|"dispatches"| node_appliance_api
node_appliance_api -->|"validates actions"| node_storage_actions
node_supervisor -->|"polls and replies"| node_appliance_api
node_supervisor -.->|"runs host actions"| node_storage_actions
node_operator -->|"searches"| node_search
node_operator -->|"evaluates policies"| node_conformity

click node_api "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/router.py"
click node_ipam "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/ipam/router.py"
click node_dns_api "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/dns/router.py"
click node_dhcp_api "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/dhcp/scopes.py"
click node_dns_import "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/dns_import/router.py"
click node_dhcp_import "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/dhcp_import/router.py"
click node_dns_agent "https://github.com/spatiumnorth/spatiumddi/blob/main/agent/dns/spatium_dns_agent/sync.py"
click node_dhcp_agent "https://github.com/spatiumnorth/spatiumddi/blob/main/agent/dhcp/spatium_dhcp_agent/sync.py"
click node_dns_drivers "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/drivers/dns/base.py"
click node_dhcp_drivers "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/drivers/dhcp/base.py"
click node_lg_agents "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/looking_glass/agents.py"
click node_route_ingest "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/looking_glass/routes_ingest.py"
click node_appliance_api "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/appliance/router.py"
click node_supervisor "https://github.com/spatiumnorth/spatiumddi/blob/main/agent/supervisor/spatium_supervisor/service_lifecycle.py"
click node_storage_actions "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/appliance/storage_actions.py"
click node_storage_health "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/appliance/storage_health.py"
click node_search "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/search/engine.py"
click node_conformity "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/conformity/engine.py"
click node_database "https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/db.py"

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_api,node_search,node_database toneBlue
class node_ipam,node_dns_api,node_dhcp_api,node_dns_import,node_dhcp_import toneAmber
class node_dns_agent,node_dhcp_agent,node_dns_drivers,node_dhcp_drivers,node_lg_agents,node_route_ingest,node_supervisor,node_dns_servers,node_dhcp_servers toneMint
class node_appliance_api,node_storage_actions,node_storage_health,node_conformity toneRose
class node_operator toneIndigo
```

## Components

### Control plane

- [REST API](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Global search](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/search/engine.py): `backend/app/services/search/engine.py`
- [Application database](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/db.py): `backend/app/db.py`

### DDI services

- [IP address management](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/ipam/router.py): `backend/app/api/v1/ipam/router.py`
- [DNS management](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/dns/router.py): `backend/app/api/v1/dns/router.py`
- [DHCP management](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/dhcp/scopes.py): `backend/app/api/v1/dhcp/scopes.py`
- [DNS import](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/dns_import/router.py): `backend/app/api/v1/dns_import/router.py`
- [DHCP import](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/dhcp_import/router.py): `backend/app/api/v1/dhcp_import/router.py`

### Agent runtime

- [DNS agent](https://github.com/spatiumnorth/spatiumddi/blob/main/agent/dns/spatium_dns_agent/sync.py): `agent/dns/spatium_dns_agent/sync.py`
- [DHCP agent](https://github.com/spatiumnorth/spatiumddi/blob/main/agent/dhcp/spatium_dhcp_agent/sync.py): `agent/dhcp/spatium_dhcp_agent/sync.py`
- [DNS server drivers](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/drivers/dns/base.py): `backend/app/drivers/dns/base.py`
- [DHCP server drivers](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/drivers/dhcp/base.py): `backend/app/drivers/dhcp/base.py`
- [Looking-glass agents](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/looking_glass/agents.py): `backend/app/api/v1/looking_glass/agents.py`
- [Route ingestion](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/looking_glass/routes_ingest.py): `backend/app/services/looking_glass/routes_ingest.py`
- [Appliance supervisor](https://github.com/spatiumnorth/spatiumddi/blob/main/agent/supervisor/spatium_supervisor/service_lifecycle.py): `agent/supervisor/spatium_supervisor/service_lifecycle.py`

### Operations

- [Appliance management](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/api/v1/appliance/router.py): `backend/app/api/v1/appliance/router.py`
- [Storage actions](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/appliance/storage_actions.py): `backend/app/services/appliance/storage_actions.py`
- [Storage health](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/appliance/storage_health.py): `backend/app/services/appliance/storage_health.py`
- [Conformity evaluation](https://github.com/spatiumnorth/spatiumddi/blob/main/backend/app/services/conformity/engine.py): `backend/app/services/conformity/engine.py`

### Other components

- **Operator**
- **DNS servers**
- **DHCP servers**

## Connections

- Operator → REST API: submits requests
- REST API → IP address management: dispatches
- REST API → DNS management: dispatches
- REST API → DHCP management: dispatches
- REST API → DNS import: dispatches
- REST API → DHCP import: dispatches
- DNS agent → DNS servers: applies configuration
- DHCP agent → DHCP servers: applies configuration
- DNS server drivers → DNS servers: controls
- DHCP server drivers → DHCP servers: controls
- Looking-glass agents → Route ingestion: pushes routes
- Route ingestion → Application database: reconciles routes
- REST API → Appliance management: dispatches
- Appliance management → Storage actions: validates actions
- Appliance supervisor → Appliance management: polls and replies
- Appliance supervisor → Storage actions: runs host actions
- Operator → Global search: searches
- Operator → Conformity evaluation: evaluates policies