#Architecture

Cascade is a multi-service platform, not a single panel binary. The current system is split between public HTTP surfaces, internal mTLS service-to-service APIs, NATS event propagation, and node-side runtime traffic.

#Overview

#Transport model

#Public HTTP

• Browser-facing auth flows land on Headwaters.
• Operator flows land on Weir.
• Tenant/customer flows land on Conduit.
• Public site and docs live in separate repos and are not service backends.

#Internal mTLS HTTP

• Weir -> Headwaters/Fabric/Ledger
• Conduit -> Fabric/Ledger/Cascadia
• Ledger -> Fabric
• Headwaters -> Fabric
• Cascadia -> Fabric
• Fabric -> Breakwater for machine-certificate issuance

#NATS

NATS is used for async backend event propagation, not primary request/response business logic.

• HTTP is used when a caller needs an immediate authoritative answer.
• NATS is used when a service announces that something happened and other services react later.

#Components

#Headwaters

• Human identity authority.
• Signup, login, session, org, invite, MFA, and OIDC/OAuth flows.
• Publishes JWT/JWKS used by downstream services.

#Fabric

• Control-plane authority.
• Tenant lifecycle, profiles, entitlements, signed actions, provisioning, node licensing, and policy bundles.
• This is the main “what exists and what is allowed?” service.

#Ledger

• Billing authority.
• Catalog, subscription state, checkout, provider webhooks, and enforcement hooks into Fabric.

#Conduit

• Tenant-facing panel backend.
• Customer, staff, billing, service, node-admin, and support APIs.
• Talks to Fabric for policy and signed actions and to Ledger for billing state.

#Cascadia

• Rust node runtime running on operator hardware.
• Maintains local state, executes workloads, syncs policy, and now performs real node-certificate activation/renewal against Fabric/Breakwater.

#Breakwater

• Machine identity and internal PKI layer.
• Current implementation now issues local service/node certificates, but full gateway/revocation/audit behavior is still being completed.

#Weir

• Operator/admin backend-for-frontend.
• Aggregates Headwaters, Fabric, and Ledger.
• Still under active hardening and not yet a finished durable source of truth.

#Exposure boundaries

#Broadly exposed

• Public site and docs
• Headwaters browser auth endpoints
• Weir operator UI/backend
• Conduit panel APIs
• Ledger user/admin/webhook routes

#Internal-only

• Fabric almost entirely
• Breakwater issuer/gateway surfaces
• Headwaters internal routes
• Ledger internal routes
• Most service-to-service traffic

#Honest current state

• Native client-certificate termination exists in Headwaters, Fabric, and Ledger.
• Conduit and Weir now use mTLS-aware upstream clients.
• Cascadia now receives its first node certificate during activation and renews real node certificates later.
• Some transition-mode forwarded-identity and durability work is still being removed or hardened.

#Web hosting request

#Game server connection

#Billing / client portal

#Security model

• All panel ↔ node communication is encrypted (TLS 1.3)
• Node registration tokens are single-use and expire after 24 hours
• Each node has a unique cryptographic identity — panel access is revocable per-node
• Workloads run in isolated environments (containers, VMs, or chroot depending on type)
• Secrets (database passwords, API keys) are encrypted at rest and never logged

#Multi-node topology

Cascade supports multiple nodes from day one. Common topologies:

Single node — All workloads on one server. Good for getting started.

Workload-separated — Dedicated nodes per workload type (web, game, database). Improves performance isolation.

Geographic distribution — Nodes in different regions. Cascade routes new workloads to the closest available node.

High availability — Two nodes in the same region with workload mirroring. Cascade handles failover automatically.