# invaliduser231/portlyn architecture

> Architecture diagram of the GitHub repository invaliduser231/portlyn, 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/invaliduser231/portlyn
- Repository: https://github.com/invaliduser231/portlyn

## Overview

1. **Top-level shape**
   Portlyn is a two-tier control-plane plus data-plane system: a Go backend that serves both the admin API and reverse-proxy traffic, and a separate Next.js frontend for administration. In the default deployment, both sit behind a Docker Compose stack with PostgreSQL, Loki, Grafana Alloy, and Grafana.

2. **Runtime entrypoints**
   The Go side is split into multiple binaries under `cmd/`: `server` is the main API/proxy process, `nodeagent` is a separate agent-oriented executable, and `configcheck` validates runtime configuration before startup. This separation is important because the main server owns control-plane state while agent behavior is isolated.

3. **Backend core responsibilities**
   The `internal/` tree shows the backend is not just an API; it combines authentication, proxying, routing, certificate automation, audit logging, rate limiting, health/metrics, and persistence. The backend is the central orchestrator that reads and writes the application’s state and then propagates configuration to the proxy runtime.

4. **Persistence boundary**
   State is stored through `internal/store/`, which contains dedicated stores for users, sessions, groups, services, domains, certificates, DNS providers, node enrollment, routing, audit records, and app settings. The README confirms PostgreSQL is the default database, with SQLite also supported, and the deployment can point to an external Postgres instance via `DATABASE_URL`.

5. **Authentication and session flow**
   Authentication is handled server-side in `internal/auth/` and `internal/http/auth.go`, with local login, OIDC/SSO, MFA, session cookies, and recovery codes. The UI uses auth-specific routes for login, OIDC callback, forbidden, and route-login flows, while the backend enforces access through middleware and route-access logic.

6. **Authorization model**
   Access control is resource-centric: services can be public, authenticated, or restricted, and restricted access is composed from users, groups, service groups, and route policies. The frontend mirrors this model with pages for services, groups, service groups, users, and access-policy fields, indicating the UI is largely a management surface over backend authorization objects.

7. **Reverse-proxy and routing path**
   The proxy subsystem under `internal/proxy/` is the runtime data-plane. It uses cached/config-bus state to serve incoming traffic, with routing definitions managed in `internal/routing/` and persisted in the store. In other words, the backend computes route state from DB objects, then the proxy layer consumes that state to forward requests to upstream services.

8. **Certificate and DNS automation**
   ACME handling is a distinct subsystem under `internal/acme/` and `internal/http/certificate_ops.go`/`certificates_dns.go`. It manages certificate issuance, renewal, retries, and status synchronization, including `http-01` and `dns-01` flows and wildcard support through DNS providers. DNS provider credentials are stored encrypted and are never returned in cleartext, which is a clear security boundary around certificate automation.

9. **Node and heartbeat boundary**
   Node enrollment and heartbeat management are first-class features in `internal/http/node_enrollment.go`, `internal/http/node_security.go`, and `internal/store/node_*`. The README indicates heartbeat tokens are stored hashed server-side and can optionally be pinned to client certificate fingerprints, so nodes are treated as trusted-but-managed agents rather than anonymous clients.

10. **Security and data protection**
   Security-sensitive concerns are centralized in `internal/secureconfig/`, `internal/http/security*.go`, and `internal/auth/`. The system uses encrypted secrets, CSRF protection, security headers, strict request parsing, admin MFA enforcement, and separate secrets for JWT/session/OIDC/CSRF/MFA/data encryption. This means the architecture assumes browser traffic, admin actions, and node traffic all need different trust controls.

11. **Observability and audit**
   Observability is split into operational telemetry and compliance-style audit logs. `internal/observability/metrics.go` and HTTP health endpoints provide liveness/readiness/health plus Prometheus-style metrics, while `internal/audit/` captures auth, proxy, and admin events. On the stack side, Loki receives logs via Alloy, and Grafana ships with provisioning and a dashboard for Portlyn-specific operational views.

12. **Frontend integration**
   The `frontend/` app is a Next.js admin console that talks to the backend API and mirrors backend resource boundaries: domains, certificates, services, nodes, users, groups, service groups, DNS providers, audit logs, settings, and system status. It is not a separate business layer; it is a management interface over the backend’s control plane.

13. **Operational packaging**
   The repository is optimized for containerized Linux deployment. `docker-compose.yml`, the root `Dockerfile`, `frontend/Dockerfile`, `deploy/` provisioning files, and `deploy.sh` define the deployment boundary, while docs cover backup/restore, HA, secret rotation, and production hardening. For an architecture diagram, the main external dependencies to show are PostgreSQL, Loki, Grafana Alloy, and Grafana, with the frontend and backend as the two primary application services.

Main entry points: [`cmd/server/main.go`](https://github.com/invaliduser231/portlyn/blob/main/cmd/server/main.go) (Server), [`docker-compose.yml`](https://github.com/invaliduser231/portlyn/blob/main/docker-compose.yml) (Compose stack), [`frontend/app/page.tsx`](https://github.com/invaliduser231/portlyn/blob/main/frontend/app/page.tsx) (Admin UI), [`internal/store/db.go`](https://github.com/invaliduser231/portlyn/blob/main/internal/store/db.go) (Stores)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_backend["Backend"]
  node_node_server["Server<br/>Go API/proxy<br/>[main.go]"]
  node_node_nodeagent["Node agent<br/>Go agent<br/>[main.go]"]
  node_node_configcheck["Config check<br/>Go validator<br/>[main.go]"]
  node_node_http["HTTP layer<br/>Handlers/middleware<br/>[server.go]"]
  node_node_auth["Auth<br/>Identity/session<br/>[service.go]"]
  node_node_proxy["Proxy<br/>Data plane<br/>[manager.go]"]
  node_node_routing["Routing<br/>Route model<br/>[types.go]"]
  node_node_acme["ACME<br/>Certificate automation<br/>[manager.go]"]
  node_node_audit["Audit<br/>Event logging<br/>[logger.go]"]
  node_node_obs["Metrics<br/>Telemetry<br/>[metrics.go]"]
  node_node_secure["Secrets<br/>Crypto/config<br/>[secrets.go]"]
end

subgraph group_group_frontend["Frontend"]
  node_node_frontend["Admin UI<br/>Next.js app<br/>[page.tsx]"]
  node_node_front_auth["Auth pages<br/>UI auth flow<br/>[page.tsx]"]
  node_node_front_dashboard["Dashboard<br/>UI shell<br/>[layout.tsx]"]
  node_node_front_resources["Resource pages<br/>UI CRUD<br/>[page.tsx]"]
end

subgraph group_group_deploy["Deployment"]
  node_node_compose["Compose stack<br/>Docker orchestration<br/>[docker-compose.yml]"]
  node_node_dockerfile["Backend image<br/>Container build"]
  node_node_front_dockerfile["Frontend image<br/>Container build"]
  node_node_alloy["Alloy<br/>Log pipeline<br/>[config.alloy]"]
  node_node_loki["Loki<br/>Log store<br/>[config.yml]"]
  node_node_grafana["Grafana<br/>Dashboards<br/>[portlyn.yml]"]
end

subgraph group_group_data["Data"]
  node_node_store[("Stores<br/>Persistence layer<br/>[db.go]")]
  node_node_db[("Database<br/>PostgreSQL/SQLite<br/>[db.go]")]
end

node_node_server -->|"serves"| node_node_http
node_node_server -->|"hosts"| node_node_proxy
node_node_server -->|"uses"| node_node_auth
node_node_server -->|"orchestrates"| node_node_acme
node_node_server -->|"emits"| node_node_audit
node_node_server -->|"exports"| node_node_obs
node_node_http -->|"reads/writes"| node_node_store
node_node_http -->|"protects"| node_node_secure
node_node_auth -->|"persists"| node_node_store
node_node_auth -->|"encrypts"| node_node_secure
node_node_proxy -->|"consumes"| node_node_routing
node_node_proxy -->|"syncs"| node_node_store
node_node_routing -->|"persists"| node_node_store
node_node_acme -->|"reads/writes"| node_node_store
node_node_acme -->|"encrypts"| node_node_secure
node_node_nodeagent -->|"enrolls with"| node_node_server
node_node_frontend -->|"calls API"| node_node_http
node_node_frontend -->|"routes"| node_node_front_auth
node_node_frontend -->|"shell"| node_node_front_dashboard
node_node_frontend -->|"manages"| node_node_front_resources
node_node_compose -->|"deploys"| node_node_server
node_node_compose -->|"deploys"| node_node_frontend
node_node_compose -->|"includes"| node_node_db
node_node_compose -->|"includes"| node_node_alloy
node_node_compose -->|"includes"| node_node_loki
node_node_compose -->|"includes"| node_node_grafana
node_node_dockerfile -->|"builds"| node_node_server
node_node_front_dockerfile -->|"builds"| node_node_frontend
node_node_store -->|"uses"| node_node_db

click node_node_server "https://github.com/invaliduser231/portlyn/blob/main/cmd/server/main.go"
click node_node_nodeagent "https://github.com/invaliduser231/portlyn/blob/main/cmd/nodeagent/main.go"
click node_node_configcheck "https://github.com/invaliduser231/portlyn/blob/main/cmd/configcheck/main.go"
click node_node_http "https://github.com/invaliduser231/portlyn/blob/main/internal/http/server.go"
click node_node_auth "https://github.com/invaliduser231/portlyn/blob/main/internal/auth/service.go"
click node_node_proxy "https://github.com/invaliduser231/portlyn/blob/main/internal/proxy/manager.go"
click node_node_routing "https://github.com/invaliduser231/portlyn/blob/main/internal/routing/types.go"
click node_node_acme "https://github.com/invaliduser231/portlyn/blob/main/internal/acme/manager.go"
click node_node_audit "https://github.com/invaliduser231/portlyn/blob/main/internal/audit/logger.go"
click node_node_obs "https://github.com/invaliduser231/portlyn/blob/main/internal/observability/metrics.go"
click node_node_secure "https://github.com/invaliduser231/portlyn/blob/main/internal/secureconfig/secrets.go"
click node_node_store "https://github.com/invaliduser231/portlyn/blob/main/internal/store/db.go"
click node_node_db "https://github.com/invaliduser231/portlyn/blob/main/internal/store/db.go"
click node_node_frontend "https://github.com/invaliduser231/portlyn/blob/main/frontend/app/page.tsx"
click node_node_front_auth "https://github.com/invaliduser231/portlyn/blob/main/frontend/app/(auth)/login/page.tsx"
click node_node_front_dashboard "https://github.com/invaliduser231/portlyn/blob/main/frontend/app/(dashboard)/layout.tsx"
click node_node_front_resources "https://github.com/invaliduser231/portlyn/blob/main/frontend/app/(dashboard)/services/page.tsx"
click node_node_compose "https://github.com/invaliduser231/portlyn/blob/main/docker-compose.yml"
click node_node_dockerfile "https://github.com/invaliduser231/portlyn/tree/main/Dockerfile"
click node_node_front_dockerfile "https://github.com/invaliduser231/portlyn/tree/main/frontend/Dockerfile"
click node_node_alloy "https://github.com/invaliduser231/portlyn/blob/main/deploy/alloy/config.alloy"
click node_node_loki "https://github.com/invaliduser231/portlyn/blob/main/deploy/loki/config.yml"
click node_node_grafana "https://github.com/invaliduser231/portlyn/blob/main/deploy/grafana/provisioning/dashboards/portlyn.yml"

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_node_server,node_node_nodeagent,node_node_configcheck,node_node_http,node_node_auth,node_node_proxy,node_node_routing,node_node_acme,node_node_audit,node_node_obs,node_node_secure toneBlue
class node_node_frontend,node_node_front_auth,node_node_front_dashboard,node_node_front_resources toneAmber
class node_node_compose,node_node_dockerfile,node_node_front_dockerfile,node_node_alloy,node_node_loki,node_node_grafana toneMint
class node_node_store,node_node_db toneRose
```

## Components

### Backend

Go control-plane, proxy runtime, and shared backend subsystems.

- [Server](https://github.com/invaliduser231/portlyn/blob/main/cmd/server/main.go): Go API/proxy · Main control-plane process serving admin API and reverse-proxy traffic. · `cmd/server/main.go`
- [Node agent](https://github.com/invaliduser231/portlyn/blob/main/cmd/nodeagent/main.go): Go agent · Separate executable for managed node behavior. · `cmd/nodeagent/main.go`
- [Config check](https://github.com/invaliduser231/portlyn/blob/main/cmd/configcheck/main.go): Go validator · Pre-start configuration validation binary. · `cmd/configcheck/main.go`
- [HTTP layer](https://github.com/invaliduser231/portlyn/blob/main/internal/http/server.go): Handlers/middleware · Admin API, auth, security, health, and resource handlers. · `internal/http/server.go`
- [Auth](https://github.com/invaliduser231/portlyn/blob/main/internal/auth/service.go): Identity/session · Login, OIDC, MFA, sessions, route access, and auth middleware. · `internal/auth/service.go`
- [Proxy](https://github.com/invaliduser231/portlyn/blob/main/internal/proxy/manager.go): Data plane · Reverse-proxy runtime consuming cached routing state. · `internal/proxy/manager.go`
- [Routing](https://github.com/invaliduser231/portlyn/blob/main/internal/routing/types.go): Route model · Routing types and policies that define request dispatch. · `internal/routing/types.go`
- [ACME](https://github.com/invaliduser231/portlyn/blob/main/internal/acme/manager.go): Certificate automation · Certificate issuance, renewal, and DNS/http validation workflows. · `internal/acme/manager.go`
- [Audit](https://github.com/invaliduser231/portlyn/blob/main/internal/audit/logger.go): Event logging · Compliance-style logging for auth, proxy, and admin events. · `internal/audit/logger.go`
- [Metrics](https://github.com/invaliduser231/portlyn/blob/main/internal/observability/metrics.go): Telemetry · Operational metrics and health reporting. · `internal/observability/metrics.go`
- [Secrets](https://github.com/invaliduser231/portlyn/blob/main/internal/secureconfig/secrets.go): Crypto/config · Encrypted secrets and secure configuration handling. · `internal/secureconfig/secrets.go`

### Frontend

Next.js administration console.

- [Admin UI](https://github.com/invaliduser231/portlyn/blob/main/frontend/app/page.tsx): Next.js app · Browser-based administration console mirroring backend resources. · `frontend/app/page.tsx`
- [Auth pages](https://github.com/invaliduser231/portlyn/blob/main/frontend/app/(auth)/login/page.tsx): UI auth flow · Login, OIDC callback, route login, and forbidden screens. · `frontend/app/(auth)/login/page.tsx`
- [Dashboard](https://github.com/invaliduser231/portlyn/blob/main/frontend/app/(dashboard)/layout.tsx): UI shell · Authenticated management surface for resources and system status. · `frontend/app/(dashboard)/layout.tsx`
- [Resource pages](https://github.com/invaliduser231/portlyn/blob/main/frontend/app/(dashboard)/services/page.tsx): UI CRUD · Pages for users, groups, services, domains, certificates, DNS providers, nodes, and audit logs. · `frontend/app/(dashboard)/services/page.tsx`

### Deployment

Container, compose, and observability packaging.

- [Compose stack](https://github.com/invaliduser231/portlyn/blob/main/docker-compose.yml): Docker orchestration · Default deployment stack wiring backend, frontend, database, and observability services. · `docker-compose.yml`
- [Backend image](https://github.com/invaliduser231/portlyn/tree/main/Dockerfile): Container build · Container build definition for the Go application. · `Dockerfile`
- [Frontend image](https://github.com/invaliduser231/portlyn/tree/main/frontend/Dockerfile): Container build · Container build definition for the Next.js app. · `frontend/Dockerfile`
- [Alloy](https://github.com/invaliduser231/portlyn/blob/main/deploy/alloy/config.alloy): Log pipeline · Grafana Alloy configuration for log shipping. · `deploy/alloy/config.alloy`
- [Loki](https://github.com/invaliduser231/portlyn/blob/main/deploy/loki/config.yml): Log store · Log aggregation backend configuration. · `deploy/loki/config.yml`
- [Grafana](https://github.com/invaliduser231/portlyn/blob/main/deploy/grafana/provisioning/dashboards/portlyn.yml): Dashboards · Provisioned dashboards and datasources for operational visibility. · `deploy/grafana/provisioning/dashboards/portlyn.yml`

### Data

Persistence and runtime state boundaries.

- [Stores](https://github.com/invaliduser231/portlyn/blob/main/internal/store/db.go): Persistence layer · Repository boundary for users, sessions, services, routing, certificates, nodes, and settings. · `internal/store/db.go`
- [Database](https://github.com/invaliduser231/portlyn/blob/main/internal/store/db.go): PostgreSQL/SQLite · Primary application persistence backing the store layer. · `internal/store/db.go`

## Connections

- Server → HTTP layer: serves · Main server exposes the HTTP/admin surface.
- Server → Proxy: hosts · Main server also runs the reverse-proxy data plane.
- Server → Auth: uses · HTTP handlers delegate authentication and session logic.
- Server → ACME: orchestrates · Server coordinates certificate issuance and renewal.
- Server → Audit: emits · Administrative and security events are audited.
- Server → Metrics: exports · Health and metrics are exposed from the backend.
- HTTP layer → Stores: reads/writes · Handlers persist and load application state through stores.
- HTTP layer → Secrets: protects · Sensitive request and secret handling uses secure config primitives.
- Auth → Stores: persists · Users, sessions, MFA, and OIDC state are stored.
- Auth → Secrets: encrypts · Auth-related secrets and tokens rely on secure secret storage.
- Proxy → Routing: consumes · Proxy runtime forwards traffic according to routing definitions.
- Proxy → Stores: syncs · Proxy state is populated from persisted configuration.
- Routing → Stores: persists · Route definitions and policy objects are stored in the database.
- ACME → Stores: reads/writes · Certificate and DNS provider state is persisted.
- ACME → Secrets: encrypts · DNS provider credentials and other secrets stay protected.
- Node agent → Server: enrolls with · Managed nodes register and heartbeat through the backend.
- Admin UI → HTTP layer: calls API · Admin UI talks to backend endpoints.
- Admin UI → Auth pages: routes · Authentication-specific pages handle login and callback flows.
- Admin UI → Dashboard: shell · Dashboard layout wraps authenticated administration pages.
- Admin UI → Resource pages: manages · Resource CRUD screens mirror backend control-plane objects.
- Compose stack → Server: deploys · Compose stack runs the Go backend service.
- Compose stack → Admin UI: deploys · Compose stack runs the admin UI.
- Compose stack → Database: includes · Primary database service is part of the default deployment.
- Compose stack → Alloy: includes · Log shipping is provided via Alloy.
- Compose stack → Loki: includes · Logs are stored in Loki.
- Compose stack → Grafana: includes · Operational dashboards are provided by Grafana.
- Backend image → Server: builds · Backend container image is built from the Go sources.
- Frontend image → Admin UI: builds · Frontend container image is built from the Next.js sources.
- Stores → Database: uses · Store layer abstracts PostgreSQL and SQLite persistence.
