c97c16a752
- Implemented Settings page for changing user passwords with validation and feedback. - Created Setup page for initial admin account setup with form handling and navigation. - Added API service layer for handling requests related to proxy hosts, remote servers, and import functionality. - Introduced mock data for testing purposes and set up testing framework with vitest. - Configured Tailwind CSS for styling and Vite for development and build processes. - Added scripts for Dockerfile validation, Python syntax checking, and Sourcery integration. - Implemented release and coverage scripts for better CI/CD practices.
3.3 KiB
3.3 KiB
CaddyProxyManager+ Architecture Plan
Stack Overview
- Backend: Go 1.24, 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 todevelopment,8080,./data/cpm.dbrespectively.internal/database: Wraps GORM + SQLite connection handling and enforces data-directory creation.internal/server: Creates Gin engine, registers middleware, wires graceful shutdown, and exposesRun(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 extendProxyHostwith 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:8080for/apipaths 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/distconsumed 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
- Version Everything (
/api/v1). - Stateless: Each request carries all context; session/story features will rely on cookies/JWT later.
- Dependable validation: Gin binding ensures HTTP 400 responses include validation errors.
- Observability: Gin logging + structured error responses keep early debugging simple; plan to add Zap/zerolog instrumentation during Beta.
Local Development Workflow
- Start backend:
cd backend && go run ./cmd/api. - Start frontend:
cd frontend && npm run dev(Vite proxy sends API calls to backend automatically). - Optional: run both via Docker (see updated Dockerfile) once containers land.
- Tests:
- Backend:
cd backend && go test ./... - Frontend build check:
cd frontend && npm run build
- Backend:
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.