# Architecture

## Layered Design

```
Handler (Gin handlers)          ← translates HTTP ↔ Service calls
    ↓
Service (business logic)        ← orchestrates, authorizes, validates
    ↓                        ↓
Repository (GORM data access)   Storage (file I/O)
    ↓                        ↓
[SQLite / PostgreSQL]        [Local FS / S3]
```

Rules:
- Handler has no business logic — parse request, call service, write response.
- Service has no HTTP awareness — operates on domain models and interfaces.
- Repository abstracts the database; Storage abstracts where bytes live.
- `internal/server` is the composition root — wires all dependencies together.

## Package Map

| Layer | Package | Purpose | Status |
|-------|---------|---------|--------|
| **CLI** | `cmd` | Cobra root command | 🛠 WIP |
| | `cmd/serve.go` | `mygo serve` — wire deps, start HTTP | 🛠 WIP |
| | `cmd/config.go` | `mygo config` — config subcommand | 🛠 WIP |
| | `cmd/status.go` | `mygo status` — health check | 🛠 WIP |
| **Config** | `internal/config` | Viper load (YAML + env + flags) | 🛠 WIP |
| **App** | `internal/app` | Runtime dependency container and build metadata | 🛠 WIP |
| **HTTP** | `internal/server` | Gin router init, route registration, graceful shutdown | 🛠 WIP |
| | `internal/handler` | HTTP handlers (auth, file, admin, webdav...) | 🛠 WIP |
| | `internal/middleware` | Gin middleware (logger, cors, auth) | 🛠 WIP |
| **Business** | `internal/service` | Business logic (auth, file, admin) | 🛠 WIP |
| | `internal/model` | Domain types (User, File, errors) | 🛠 WIP |
| **Data** | `internal/repository` | Repository interfaces + GORM implementations | 🛠 WIP |
| | `internal/storage` | Storage backend interface + local disk impl | 🛠 WIP |
| **Util** | `internal/auth` | JWT sign/verify, context helpers | 🛠 WIP |
| | `internal/api` | Error body helpers | 🛠 WIP |

## API Routes (v0)

```
GET /api/v1/version

POST /api/v1/auth/register
POST /api/v1/auth/login
POST /api/v1/auth/refresh

GET   /api/v1/users/me
PATCH /api/v1/users/me

GET    /api/v1/files
POST   /api/v1/files
GET    /api/v1/files/:id
GET    /api/v1/files/:id/content
PUT    /api/v1/files/:id
DELETE /api/v1/files/:id

GET    /api/v1/admin/users
GET    /api/v1/admin/users/:id
PUT    /api/v1/admin/users/:id
DELETE /api/v1/admin/users/:id
```

## Middleware Chain

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 (`router.go`), route registration split into `routes_public.go` and `routes_protected.go`, and HTTP server lifecycle.
- `RunWithGracefulShutdown` stops accepting new requests on termination and gives in-flight requests time to finish.