mygo/docs/decisions.md

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 sessions table and a repository.SessionRepository interface.
• UUID dependency: github.com/google/uuid to 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)	Public routes (routes_public.go) and protected routes (routes_protected.go) split by auth boundary; WebApp serves as the unified dependency container.
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/app/version.go, not a config-file field.
• app.WebApp is 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.