Implement web API foundation

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

docs/architecture.md

@@ -23,23 +23,26 @@ Rules:
 | Layer | Package | Purpose | Status |
 |-------|---------|---------|--------|
 | **CLI** | `cmd` | Cobra root command | ✅ skeleton |
-| | `cmd/serve.go` | `mygo serve` — wire deps, start HTTP | ⬜ plan |
+| | `cmd/serve.go` | `mygo serve` — wire deps, start HTTP | ✅ skeleton |
 | | `cmd/config.go` | `mygo config` — config subcommand | ⬜ plan |
 | | `cmd/status.go` | `mygo status` — health check | ⬜ plan |
-| **Config** | `internal/config` | Viper load (YAML + env + flags) | ⬜ plan |
-| **HTTP** | `internal/server` | Gin engine init, route registration, middleware chain | ⬜ plan |
-| | `internal/handler` | HTTP handlers (auth, file, admin, webdav...) | ⬜ plan |
-| | `internal/middleware` | Gin middleware (requestid, logger, cors, auth) | ⬜ plan |
+| **Config** | `internal/config` | Viper load (YAML + env + flags) | ✅ skeleton |
+| **App** | `internal/app` | Runtime dependency container and build metadata | ✅ skeleton |
+| **HTTP** | `internal/server` | Gin router init, route registration, graceful shutdown | ✅ skeleton |
+| | `internal/handler` | HTTP handlers (auth, file, admin, webdav...) | ✅ skeleton |
+| | `internal/middleware` | Gin middleware (logger, cors, auth) | ⬜ plan |
 | **Business** | `internal/service` | Business logic (auth, file, admin) | ⬜ plan |
 | | `internal/model` | Domain types (User, File, errors) | ⬜ plan |
 | **Data** | `internal/repository` | Repository interfaces + GORM implementations | ⬜ plan |
 | | `internal/storage` | Storage backend interface + local disk impl | ⬜ plan |
 | **Util** | `internal/auth` | JWT sign/verify, context helpers | ⬜ plan |
-| | `internal/api` | JSON response writer, error code helpers | ⬜ plan |
+| | `internal/api` | Error body helpers | ✅ skeleton |
 
 ## API Routes (v0)
 
 ```
+GET /api/v1/version
+
 POST /api/v1/auth/register
 POST /api/v1/auth/login
 POST /api/v1/auth/refresh
@@ -62,6 +65,15 @@ DELETE /api/v1/admin/users/:id
 
 ## Middleware Chain
 
-Applied globally: requestid → logger → cors
+Applied globally by `gin.Default()`: logger → recovery
+
+Planned globally: cors
 
 Applied to protected groups: auth (JWT validation, inject user into gin.Context)
+
+## Server Responsibilities
+
+- `cmd/serve.go` loads config, creates `app.WebApp`, builds the router, and starts the HTTP server.
+- `app.WebApp` carries runtime dependencies and build metadata needed to assemble handlers.
+- `internal/server` owns Gin router setup, `/api/v1` route groups, and HTTP server lifecycle.
+- `RunWithGracefulShutdown` stops accepting new requests on termination and gives in-flight requests time to finish.

docs/decisions.md

@@ -16,7 +16,7 @@
 | 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 |
+| 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.
 
@@ -25,4 +25,26 @@
 - 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).
+- 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.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.

docs/roadmap.md

@@ -6,6 +6,7 @@
 |---------|--------|-------|
 | CLI config management | ⬜ plan | |
 | JWT authentication | ⬜ plan | access + refresh tokens, refresh token in DB |
+| Web API foundation | ✅ skeleton | WebApp composition, Gin router, graceful shutdown, `GET /api/v1/version` |
 | File upload/download/manage APIs | ⬜ plan | REST API via Gin |
 | Admin endpoints | ⬜ plan | user CRUD for superusers |
 | WebDAV | ⬜ plan | future v0 or v1 |
@@ -15,17 +16,18 @@
 Package-level implementation order (each task includes unit tests):
 
 1. `internal/config` — Viper loader, config struct
-2. `internal/model` — domain types, error codes
-3. `internal/api` — JSON response helpers
-4. `internal/auth` — JWT utils
-5. `internal/storage` — backend interface + local fs
-6. `internal/repository` — interfaces + GORM/SQLite impl
-7. `internal/service` — auth, file, admin services
-8. `internal/middleware` — requestid, logger, cors, auth
-9. `internal/handler` — auth, file, admin handlers
-10. `internal/server` — Gin wiring, route registration
-11. `cmd/serve.go`, `cmd/config.go`, `cmd/status.go`
-12. Integration tests
+2. `internal/app` — runtime dependency container ✅ skeleton
+3. `internal/model` — domain types, error codes
+4. `internal/api` — error response helpers ✅ skeleton
+5. `internal/auth` — JWT utils
+6. `internal/storage` — backend interface + local fs
+7. `internal/repository` — interfaces + GORM/SQLite impl
+8. `internal/service` — auth, file, admin services
+9. `internal/middleware` — logger, cors, auth
+10. `internal/handler` — auth, file, admin handlers ✅ version skeleton
+11. `internal/server` — Gin router, route registration, graceful shutdown ✅ skeleton
+12. `cmd/serve.go`, `cmd/config.go`, `cmd/status.go` ✅ serve skeleton
+13. Integration tests
 
 ## Future