# Server Layer

The root package owns Gin server lifecycle and Swagger setup. HTTP concerns are
grouped by role:

- `handler/`: resource handlers and HTTP boundary validation
- `middleware/`: request metadata, auth, access control, audit, recovery, CORS
- `router/`: resource route registration and the system route registrar
- `pkg/httpx/`: transport-level response and cookie helpers shared by handlers
  and middleware
- `staticfiles/`: local upload storage route registration and file serving

Cross-cutting route policy lives in `internal/routecatalog`: public/private
Swagger security, operation-audit flags, sensitive request-body handling and
API group/description metadata must be declared there. Router contract tests
keep the catalog aligned with the Gin registrations.

Keep new files in the matching role directory instead of adding transport files
to the root package.

`middleware/` intentionally remains under `internal/server`: authentication,
access control, audit, rate limiting and CORS depend on application config and
services. Only dependency-free transport helpers belong in `pkg`; they should
not be moved to `internal/utils`, which is reserved for stateless application
helpers.
