Executive Overview

Cirrus CDN delivers a programmable content delivery network oriented toward operators who require tight control over origin routing, TLS automation, and operational telemetry. The control plane is built around FastAPI services, Redis-backed configuration, and a Next.js administration portal, while the data plane relies on OpenResty to serve and cache traffic. This chapter summarizes the mission, stakeholders, differentiators, and guiding principles that shape the platform.

Mission Statement

Cirrus CDN aims to:

• Provide a unified control surface for managing CDN sites, nodes, and caching policy.
• Automate certificate provisioning and renewal via ACME DNS-01 challenges.
• Expose deterministic, health-aware traffic steering through internally managed DNS.
• Deliver first-class observability so SRE and operations teams can close the loop quickly.
• Minimize toil by packaging infrastructure within reproducible Docker orchestration.

Target Stakeholders

Persona	Needs	Cirrus Capabilities
CDN / Platform Engineers	Programmatic APIs for domain onboarding, node lifecycle, purge actions.	REST API under src/cirrus/api/*, typed schemas in schemas.py, service tokens for automation.
SRE / On-call Staff	Health signals, metrics, ability to quarantine nodes, easy reconfiguration.	Redis-backed status, Celery health checks (cirrus/cname/health.py), Prometheus metrics, /api/v1/nodes endpoint.
Security Engineers	Certificate management, auditability, controlled secrets handling.	ACME automation (cirrus/celery_app.py), hashed tokens (core/tokens.py), dynamic TLS loading in OpenResty.
Delivery / Operations	Turn-key deployment, documentation, dashboards, repeatable workflows.	docker-compose.yml, justfile, Grafana + Prometheus stack, this white paper.

Platform Differentiators

• End-to-end automation: ACME issuance and renewals are baked into the control plane and executed via Celery workers, eliminating ad-hoc scripts.
• Integrated DNS authority: The system synthesizes authoritative DNS zones (hidden master + NSD slave) to steer clients toward healthy edge nodes using rendezvous hashing.
• Config-in-Redis: All mutable state—domains, nodes, certificates, purge queues—is stored in Redis. This provides atomic updates, pub/sub notifications, and easy inspection.
• Composable frontend: The Next.js portal consumes the same REST APIs as external clients, ensuring equivalence between manual and automated workflows.
• Observability-first: OpenResty emits Prometheus metrics, health checks update node status, and logs are rotated automatically; these are first-class citizens, not afterthoughts.

Guiding Principles

1. Operational clarity: Each subsystem (API, DNS, edge, automation) favors explicit Redis keys and observable actions over hidden behavior.
2. Deterministic behavior: Rendezvous hashing, lock-based ACME flows, and idempotent APIs are used to avoid race conditions.
3. Security by default: Passwords are Argon2 hashed, tokens are SHA-256 hashed, TLS certificates never touch disk outside Redis/edge memory, and master tokens gate privileged operations.
4. Extensibility: Docker-based deployment and modular Python/Lua components allow teams to swap integrations (e.g., external DNS secondaries, additional metrics sinks).
5. Developer productivity: A justfile codifies common workflows (just up, just pytest, just deploy) to encourage consistent practice across contributors.

Document Roadmap

Subsequent chapters drill into each subsystem. Readers who want a high-level understanding should skim Chapters 2 and 3. Teams responsible for automation, DNS, or edge operations should review Chapters 4–6. Frontend maintainers should reference Chapter 7, while security and compliance readers should focus on Chapter 8. Operations and SRE staff should emphasize Chapters 9 and 10. Chapter 11 collects appendices and reference tables for quick lookup. The chapters cross-reference code paths (for example, src/cirrus/app.py:21 for API bootstrap) to ensure accuracy against the repository.