# syklonak/ng-control-plane architecture

> Architecture diagram of the GitHub repository syklonak/ng-control-plane, 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/syklonak/ng-control-plane
- Repository: https://github.com/syklonak/ng-control-plane

## Overview

pg-router is a configuration-driven Nginx control plane, not a traffic proxy. Its principal workflow loads and validates a declarative routing topology, resolves its backend and tunnel endpoints, generates Nginx fragments, then tests and deploys them; Nginx serves production traffic. The graph also includes configuration authoring and management, status and health, rollback, and Nginx installation/operations. Some internal relationships are supported by the source index rather than inspected implementation; those edges cite the caller file or README as available evidence.

Main entry points: [`pg_router/services/services.py`](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/services/services.py) (Command services), [`pg_router/deploy/deployer.py`](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/deploy/deployer.py) (Atomic deployer), [`pg_router/config/validator.py`](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/config/validator.py) (Config validator), [`pg_router/nginx/generator.py`](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/nginx/generator.py) (Nginx generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["CLI<br/>[app.py]"]
  node_menu["Interactive menu<br/>[menu.py]"]
  node_wizard["Config wizard<br/>[wizard.py]"]
  node_services["Command services<br/>[services.py]"]
end

subgraph group_configuration["Configuration"]
  node_config_management["Config management<br/>[management.py]"]
  node_loader["Config loader<br/>[loader.py]"]
  node_schema["Config schema<br/>[schema.py]"]
  node_validator["Config validator<br/>[validator.py]"]
end

subgraph group_routing["Routing model"]
  node_topology["Topology resolver<br/>[topology.py]"]
  node_selection["Route selection<br/>[selection.py]"]
  node_matcher["Route matcher<br/>[matcher.py]"]
  node_capabilities["Capabilities<br/>[capabilities.py]"]
  node_providers["Provider adapters<br/>[providers.py]"]
  node_registry["Provider registry<br/>[registry.py]"]
end

subgraph group_operations["Nginx operations"]
  node_generator["Nginx generator<br/>[generator.py]"]
  node_deployer["Atomic deployer<br/>[deployer.py]"]
  node_health["Health checks<br/>[health.py]"]
  node_nginx_manager["Nginx manager<br/>[manager.py]"]
  node_installer["Nginx installer<br/>[installer.py]"]
  node_modules["Module detection<br/>[modules.py]"]
end

node_operator(("Operator"))
node_config_file["Routing config"]
node_nginx["Nginx"]

node_operator -->|"invokes"| node_cli
node_cli -->|"opens"| node_menu
node_cli -->|"launches"| node_wizard
node_cli -->|"delegates"| node_services
node_services -->|"manages files"| node_config_management
node_operator -->|"authors"| node_config_file
node_wizard -->|"creates"| node_config_file
node_config_management -->|"reads and edits"| node_config_file
node_services -->|"loads"| node_loader
node_loader -->|"parses into"| node_schema
node_validator -->|"checks objects"| node_schema
node_services -->|"validates"| node_validator
node_validator -->|"compiles routes"| node_selection
node_validator -->|"checks compatibility"| node_capabilities
node_services -->|"resolves endpoints"| node_topology
node_topology -->|"resolves providers"| node_registry
node_services -->|"simulates routes"| node_matcher
node_generator -->|"consumes resolved routes"| node_topology
node_generator -->|"uses selections"| node_selection
node_generator -->|"resolves certificates"| node_registry
node_providers -->|"registers adapters"| node_registry
node_services -->|"generates fragments"| node_generator
node_deployer -->|"validates config"| node_validator
node_deployer -->|"resolves topology"| node_topology
node_deployer -->|"generates fragments"| node_generator
node_deployer -->|"tests and reloads"| node_nginx_manager
node_services -->|"applies changes"| node_deployer
node_services -->|"checks health"| node_health
node_health -->|"uses probe providers"| node_registry
node_services -->|"runs operations"| node_nginx_manager
node_installer -->|"detects modules"| node_modules
node_installer -->|"configures Nginx"| node_nginx_manager
node_nginx_manager -->|"detects capabilities"| node_modules
node_nginx_manager -->|"tests and controls"| node_nginx
node_installer -->|"installs packages"| node_nginx
node_nginx -->|"serves traffic"| node_operator

click node_cli "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/cli/app.py"
click node_menu "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/cli/menu.py"
click node_wizard "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/cli/wizard.py"
click node_services "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/services/services.py"
click node_config_management "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/config/management.py"
click node_loader "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/config/loader.py"
click node_schema "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/config/schema.py"
click node_validator "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/config/validator.py"
click node_topology "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/model/topology.py"
click node_selection "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/model/selection.py"
click node_matcher "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/model/matcher.py"
click node_capabilities "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/model/capabilities.py"
click node_providers "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/plugins/providers.py"
click node_registry "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/plugins/registry.py"
click node_generator "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/nginx/generator.py"
click node_deployer "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/deploy/deployer.py"
click node_health "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/deploy/health.py"
click node_nginx_manager "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/nginx/manager.py"
click node_installer "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/nginx/installer.py"
click node_modules "https://github.com/syklonak/ng-control-plane/blob/main/pg_router/nginx/modules.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_cli,node_menu,node_wizard,node_services toneBlue
class node_config_management,node_loader,node_schema,node_validator toneAmber
class node_topology,node_selection,node_matcher,node_capabilities,node_providers,node_registry toneMint
class node_generator,node_deployer,node_health,node_nginx_manager,node_installer,node_modules toneRose
class node_operator,node_config_file,node_nginx toneIndigo
```

## Components

### User interface

- [CLI](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/cli/app.py): `pg_router/cli/app.py`
- [Interactive menu](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/cli/menu.py): `pg_router/cli/menu.py`
- [Config wizard](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/cli/wizard.py): `pg_router/cli/wizard.py`
- [Command services](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/services/services.py): `pg_router/services/services.py`

### Configuration

- [Config management](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/config/management.py): `pg_router/config/management.py`
- [Config loader](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/config/loader.py): `pg_router/config/loader.py`
- [Config schema](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/config/schema.py): `pg_router/config/schema.py`
- [Config validator](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/config/validator.py): `pg_router/config/validator.py`

### Routing model

- [Topology resolver](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/model/topology.py): `pg_router/model/topology.py`
- [Route selection](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/model/selection.py): `pg_router/model/selection.py`
- [Route matcher](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/model/matcher.py): `pg_router/model/matcher.py`
- [Capabilities](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/model/capabilities.py): `pg_router/model/capabilities.py`
- [Provider adapters](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/plugins/providers.py): `pg_router/plugins/providers.py`
- [Provider registry](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/plugins/registry.py): `pg_router/plugins/registry.py`

### Nginx operations

- [Nginx generator](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/nginx/generator.py): `pg_router/nginx/generator.py`
- [Atomic deployer](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/deploy/deployer.py): `pg_router/deploy/deployer.py`
- [Health checks](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/deploy/health.py): `pg_router/deploy/health.py`
- [Nginx manager](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/nginx/manager.py): `pg_router/nginx/manager.py`
- [Nginx installer](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/nginx/installer.py): `pg_router/nginx/installer.py`
- [Module detection](https://github.com/syklonak/ng-control-plane/blob/main/pg_router/nginx/modules.py): `pg_router/nginx/modules.py`

### Other components

- **Operator**
- **Routing config**
- **Nginx**

## Connections

- Operator → CLI: invokes (evidence: `README.md`)
- CLI → Interactive menu: opens (evidence: `pg_router/cli/app.py`)
- CLI → Config wizard: launches (evidence: `pg_router/cli/app.py`)
- CLI → Command services: delegates (evidence: `pg_router/cli/app.py`)
- Command services → Config management: manages files (evidence: `pg_router/services/services.py`)
- Operator → Routing config: authors (evidence: `README.md`)
- Config wizard → Routing config: creates (evidence: `README.md`)
- Config management → Routing config: reads and edits (evidence: `README.md`)
- Command services → Config loader: loads (evidence: `pg_router/services/services.py`)
- Config loader → Config schema: parses into (evidence: `pg_router/config/loader.py`)
- Config validator → Config schema: checks objects (evidence: `pg_router/config/validator.py`)
- Command services → Config validator: validates (evidence: `pg_router/services/services.py`)
- Config validator → Route selection: compiles routes (evidence: `pg_router/config/validator.py`)
- Config validator → Capabilities: checks compatibility (evidence: `pg_router/config/validator.py`)
- Command services → Topology resolver: resolves endpoints (evidence: `pg_router/services/services.py`)
- Topology resolver → Provider registry: resolves providers (evidence: `pg_router/model/topology.py`)
- Command services → Route matcher: simulates routes (evidence: `pg_router/services/services.py`)
- Nginx generator → Topology resolver: consumes resolved routes (evidence: `pg_router/nginx/generator.py`)
- Nginx generator → Route selection: uses selections (evidence: `pg_router/nginx/generator.py`)
- Nginx generator → Provider registry: resolves certificates (evidence: `pg_router/nginx/generator.py`)
- Provider adapters → Provider registry: registers adapters (evidence: `pg_router/plugins/providers.py`)
- Command services → Nginx generator: generates fragments (evidence: `pg_router/services/services.py`)
- Atomic deployer → Config validator: validates config (evidence: `pg_router/deploy/deployer.py`)
- Atomic deployer → Topology resolver: resolves topology (evidence: `pg_router/deploy/deployer.py`)
- Atomic deployer → Nginx generator: generates fragments (evidence: `pg_router/deploy/deployer.py`)
- Atomic deployer → Nginx manager: tests and reloads (evidence: `pg_router/deploy/deployer.py`)
- Command services → Atomic deployer: applies changes (evidence: `pg_router/services/services.py`)
- Command services → Health checks: checks health (evidence: `pg_router/services/services.py`)
- Health checks → Provider registry: uses probe providers (evidence: `pg_router/deploy/health.py`)
- Command services → Nginx manager: runs operations (evidence: `pg_router/services/services.py`)
- Nginx installer → Module detection: detects modules (evidence: `pg_router/nginx/installer.py`)
- Nginx installer → Nginx manager: configures Nginx (evidence: `pg_router/nginx/installer.py`)
- Nginx manager → Module detection: detects capabilities (evidence: `pg_router/nginx/manager.py`)
- Nginx manager → Nginx: tests and controls (evidence: `pg_router/nginx/manager.py`)
- Nginx installer → Nginx: installs packages (evidence: `README.md`)
- Nginx → Operator: serves traffic (evidence: `README.md`)
