Huxley
7fb125ea87
Add application container, Gin router, graceful shutdown handler, and version endpoint. This establishes the skeleton for the WebDisk HTTP API as described in the architecture. - Add internal/app/WebApp for runtime dependencies and version - Add internal/server/router with GET /api/v1/version route - Add graceful shutdown runner with signal handling in cmd/serve - Add internal/api/ErrorResponse for standard HTTP error body - Update roadmap, architecture, and decisions documentation
3.5 KiB
3.5 KiB
Technical Decisions
2026-04-25: v0 Tech Stack & Architecture
Context: Project skeleton was created with only cobra CLI. We needed a concrete tech stack and package layout to begin implementation.
Decisions:
| Area | Choice | Rationale |
|---|---|---|
| HTTP framework | Gin | Most widely adopted Go web framework, mature middleware ecosystem |
| ORM | GORM | SQLite-first dev, PostgreSQL option later; GORM abstracts dialect differences |
| Config management | Viper | YAML + env vars + CLI flags three-way merge, built for cobra integration |
| Database | SQLite (v0) → PostgreSQL (future) | SQLite zero setup for dev; repo interface isolates the switch |
| File storage | Local disk (v0) → S3 (future) | Backend interface (internal/storage) hides implementation |
| File identity | UUID | Distributed-friendly, no coordination needed; cost is negligible for file metadata |
| Token strategy | JWT, refresh token stored in DB | Enables server-side revocation (admin kick, logout-all-devices) |
| Pagination | OFFSET/LIMIT | Simple, sufficient for v0; migrate to cursor-based if needed |
| API response format | Direct JSON success bodies + unified error body | HTTP status codes carry request outcome; error body carries human-readable details |
Architecture: Four-layer model — Handler (Gin) → Service (business logic) → Repository (GORM data access) + Storage (file I/O). Each layer depends only on interfaces of the layer below.
Consequences:
- Handler layer has no business logic; Service layer is reusable across REST API, WebDAV, and future Nextcloud API.
- Repository interfaces keep DB swappable; future PostgreSQL implementation only needs a new package.
- Refresh token in DB adds a
sessionstable and arepository.SessionRepositoryinterface. - UUID dependency:
github.com/google/uuidto be added. - Gin middleware chain: default logger/recovery → cors → auth (route-group-scoped).
2026-04-27: Web API Foundation
Context: The project needed the first HTTP slice that can validate Gin wiring and provide a stable shape for future auth, file, and admin APIs.
Decisions:
| Area | Choice | Guidance |
|---|---|---|
| API versioning | All REST routes under /api/v1 |
Keep future REST handlers under the versioned group. |
| Initial public endpoint | GET /api/v1/version |
Returns build metadata only; health/readiness endpoints need a separate security review. |
| Success responses | Direct JSON resource bodies | Use HTTP status codes as the request outcome signal. |
| Error responses | {"error":{"message":"..."}} |
Add machine-readable error codes only when clients need stable branching behavior. |
| App composition | internal/app.WebApp |
cmd/serve.go creates the app from config and build metadata, then passes it to router setup. |
| Router setup | internal/server.NewRouter(*app.WebApp) |
Register public and protected route groups in one readable router file. |
| Server lifecycle | RunWithGracefulShutdown |
Preserve graceful shutdown while keeping command startup linear. |
| Default middleware | gin.Default() |
Use default logger/recovery for the skeleton; add CORS/auth explicitly when their policies exist. |
Consequences:
- Version is build metadata from
internal/version, not a config-file field. app.WebAppis the place to add future services, repositories, storage, and app metadata incrementally.- Request ID middleware is not part of the current foundation; add it only with a logging/tracing/error-correlation design.