Architecture¶
CaddyBuddy is a server-rendered FastAPI application backed by SQLAlchemy and SQLite.
Main layers¶
| Layer | Location | Responsibility |
|---|---|---|
| Configuration | app/config | Environment validation, logging, limiter configuration |
| Routers | app/routers | HTML pages and JSON endpoints |
| Services | app/services | Caddy integration, onboarding, SSL Labs, certificates, events |
| Repositories | app/repositories | Database access |
| Models and schemas | app/models, app/schemas | Persistence and response contracts |
| Templates and assets | app/templates, app/static | Server-rendered UI and browser behavior |
Configuration flow¶
- Site and runtime settings are stored in SQLite.
- CaddyBuddy assembles the baseline, snippets, and enabled site definitions.
- The candidate Caddyfile is validated.
- The managed Caddyfile is persisted before the configuration is loaded through the private Caddy Admin API.
- If loading fails, CaddyBuddy attempts to restore the previous managed Caddyfile.
- The managed Caddyfile and runtime state are reconciled.
Live updates¶
The application uses server-sent events to notify authenticated browser sessions about resource changes. Dashboard and related views refresh their data after receiving an event.
Design boundary¶
CaddyBuddy manages a single Caddy installation. It is not a multi-node orchestrator and does not replace host-level backup, firewall, monitoring, or secret-management systems.