# CaddyProxyManager+ Architecture Plan

## Stack Overview
- **Backend**: Go 1.22, Gin HTTP framework, GORM ORM, SQLite for local/stateful storage.
- **Frontend**: React 18 + TypeScript with Vite, React Query for data fetching, React Router for navigation.
- **API Contract**: REST/JSON over `/api/v1`, versioned to keep room for breaking changes.
- **Deployment**: Container-first via multi-stage Docker build (Node → Go), future compose bundle for Caddy runtime.

## Backend
- `backend/cmd/api`: Entry point wires configuration, database, and HTTP server lifecycle.
- `internal/config`: Reads environment variables (`CPM_ENV`, `CPM_HTTP_PORT`, `CPM_DB_PATH`). Defaults to `development`, `8080`, `./data/cpm.db` respectively.
- `internal/database`: Wraps GORM + SQLite connection handling and enforces data-directory creation.
- `internal/server`: Creates Gin engine, registers middleware, wires graceful shutdown, and exposes `Run(ctx)` for signal-aware lifecycle.
- `internal/api`: Versioned routing layer. Initial resources:
  - `GET /api/v1/health`: Simple status response for readiness checks.
  - CRUD `/api/v1/proxy-hosts`: Minimal data model used to validate persistence, shape matches Issue #1 requirements (name, domain, upstream target, toggles).
- `internal/models`: Source of truth for persistent entities. Future migrations will extend `ProxyHost` with SSL, ACL, audit metadata.
- Testing: In-memory SQLite harness verifies handler lifecycle via unit tests (`go test ./...`).

## Frontend
- Vite dev server with proxy to `http://localhost:8080` for `/api` paths keeps CORS trivial.
- React Router organizes initial pages (Dashboard, Proxy Hosts, System Status) to mirror Issue roadmap.
- React Query centralizes API caching, invalidation, and loading states.
- Basic layout shell provides left-nav reminiscent of NPM while keeping styling simple (CSS utility file, no design system yet). Future work will slot shadcn/ui components without rewriting data layer.
- Build outputs static assets in `frontend/dist` consumed by Docker multi-stage for production.

## Data & Persistence
- SQLite chosen for Alpha milestone simplicity; GORM migrates schema automatically on boot (`AutoMigrate`).
- Database path configurable via env to allow persistent volumes in Docker or alternative DB (PostgreSQL/MySQL) when scaling.

## API Principles
1. **Version Everything** (`/api/v1`).
2. **Stateless**: Each request carries all context; session/story features will rely on cookies/JWT later.
3. **Dependable validation**: Gin binding ensures HTTP 400 responses include validation errors.
4. **Observability**: Gin logging + structured error responses keep early debugging simple; plan to add Zap/zerolog instrumentation during Beta.

## Local Development Workflow
1. Start backend: `cd backend && go run ./cmd/api`.
2. Start frontend: `cd frontend && npm run dev` (Vite proxy sends API calls to backend automatically).
3. Optional: run both via Docker (see updated Dockerfile) once containers land.
4. Tests:
   - Backend: `cd backend && go test ./...`
   - Frontend build check: `cd frontend && npm run build`

## Next Steps
- Layer authentication (Issue #7) once scaffolding lands.
- Expand data model (certificates, access lists) and add migrations.
- Replace basic CSS with component system (e.g., shadcn/ui) + design tokens.
- Compose file bundling backend, frontend assets, Caddy runtime, and SQLite volume.