System Overview

Planekeeper is a Go- and Postgres-backed service with remote agents that introspect version information from code repositories and normalize release metadata so rules can be applied to detect out-of-date software versions.

Architecture Diagram

                    Internet
                        |
        +---------------+---------------+
        |   traefik-public (80/443)     |
        |   - Client UI (/)             |
        |   - Client API (/api/v1/client)|
        |   - Agent API (/api/v1/agent) |
        |   - Public Docs (/docs)       |
        |   - Early Access (/earlyaccess)|
        |   - Swagger UI (/api/v1/swagger)|
        +---------------+---------------+
                        |
        +---------------+---------------+
        |               v               |
        |  +---------+ +-------------+  |
        |  |   API   | |  Client UI  |  |
        |  +----+----+ +-------------+  |
        |       |                       |
        |  +----+----+ +-------------+  |
        |  |PostgreSQL| | Internal UI |  |
        |  +---------+ +------+------+  |
        |                     |         |
        |  +-------------+ +----------+ |
        |  | TaskEngine  | |ServerAgent||
        |  +-------------+ +----------+ |
        |  +-------------+ +----------+ |
        |  |  Notifier   | |EarlyAccess||
        |  +-------------+ +----------+ |
        |  +------+ +---------------+   |
        |  | Docs | | Internal Docs |   |
        |  +------+ +---------------+   |
        +---------------------+---------+
                              |
        +---------------------v---------+
        | traefik-internal (8443/8082)  |
        | - Internal UI (/)             |
        | - Internal API (/api/v1/internal)|
        | - Internal Docs (/docs)       |
        | - Early Access Admin (/earlyaccess)|
        +-------------------------------+
                  ^
            Firewall-restricted IP

Service Descriptions

Service	Role
Server (API)	Hosts the REST API, runs migrations, manages background services
ClientUI	Public-facing UI for end users
InternalUI	Admin UI for system management (port 8443, firewall-restricted)
ServerAgent	Polls for tasks, executes gather/scrape jobs (co-located in Docker network)
ClientAgent	Same as ServerAgent but deployed remotely at client sites
TaskEngine	Handles job scheduling, timeout management, and result processing
EOLSync	Scheduled sync of endoflife.date data
Notifier	Delivers webhook notifications for alert events with retry logic
EarlyAccess	Waitlist form and admin management for early access signups
Docs	Public Hugo (docs theme) documentation site (nginx)
Internal Docs	Internal Hugo (docs theme) documentation site (nginx)

Split Traefik Architecture

The deployment uses two separate Traefik reverse proxy instances:

traefik-public (ports 80/443): Exposes only client-facing endpoints — Client UI, Client API, Agent API, public docs, early access, and Swagger UI
traefik-internal (port 8443): Exposes admin/internal endpoints — Internal UI, Internal API, internal docs, and early access admin. TLS via Let’s Encrypt DNS-01. Accessible only via firewall-restricted IP.

Public Traefik Routes

Router	Rule	Service	Priority
`client-api`	`PathPrefix(/api/v1/client)`	api (3000)	100
`agent-api`	`PathPrefix(/api/v1/agent)`	api (3000)	100
`health`	`Path(/health)`	api (3000)	100
`swagger-client`	`PathPrefix(/api/v1/swagger)`	api (3000)	100
`api-specs`	`PathPrefix(/api/)`	api (3000)	50
`docs`	`PathPrefix(/docs)`	docs (8080)	100
`earlyaccess`	`Path(/earlyaccess)`	earlyaccess (3000)	100
`clientui`	Catch-all	clientui (3000)	1

Internal Traefik Routes

Router	Rule	Service	Priority
`internal-api`	`PathPrefix(/api/v1/internal)`	api (3000)	100
`health`	`Path(/health)`	api (3000)	100
`api-specs`	`PathPrefix(/api/spec)`	api (3000)	100
`earlyaccess`	`PathPrefix(/earlyaccess)`	earlyaccess (3000)	100
`internal-docs`	`PathPrefix(/docs)`	internal-docs (8080)	100
`internalui`	`PathPrefix(/)`	internalui (3000)	1

Key Design Decisions

Multi-tenant: Organizations provide the tenant boundary. All data is scoped to an organization.
Dual auth: The API server supports both JWT (Supabase) and API key authentication.
Agent-based: Remote agents poll the server for tasks, enabling deployment at client sites behind firewalls.
Event-driven alerts: Rule evaluation triggers events that the notification system subscribes to.
Docker-native: All development tools and production deployment use Docker containers.

Binaries & Services — Detailed binary descriptions and service IDs
Project Structure — Full directory tree
Deployment — Docker Compose deployment guide