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	{code, message, data}	Consistent envelope across all endpoints

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: requestid → logger → cors → auth (route-group-scoped).