Architecture¶
The code is organised in feature packages on top of a small platform layer, wired together in one place.
flowchart TD
cmd["cmd/api · cmd/migrate"] --> app
app["internal/app<br>composition root"] --> users["internal/users"]
app --> tasks["internal/tasks"]
app --> auth["internal/auth"]
app --> config["internal/config"]
users --> auth
tasks --> auth
users --> platform
tasks --> platform
auth --> platform["internal/platform<br>database · httpx · middleware · contract · errs"]
auth --> config
platform --> config
platform --> migrations["migrations"]
app --> api["api<br>openapi.yaml"]
Packages¶
| Package | Responsibility |
|---|---|
cmd/api |
Entry point of the server. Parses flags, loads the configuration, runs the application. |
cmd/migrate |
Entry point of the migration command: up, down, status. |
api |
The OpenAPI document, embedded with go:embed. |
migrations |
The SQL migrations, one directory per driver, embedded. |
internal/app |
The composition root. app.go constructs every component; routes.go builds the router. |
internal/app/apptest |
Starts the whole application for end-to-end tests. |
internal/config |
Declares, loads and validates every environment variable. |
internal/auth |
Password hashing, access and refresh tokens, the authentication middleware and the /auth endpoints. |
internal/users |
The users feature: model, service, repository, handler. |
internal/tasks |
The example feature, and the source the resource generator copies. |
internal/platform/database |
Connection, driver registry, placeholder rewriting, transactions, migrations. |
internal/platform/httpx |
The HTTP conventions: JSON, problem responses, pagination, ETag. |
internal/platform/middleware |
Request ID, logging, recovery, security headers, metrics, rate limiting. |
internal/platform/contract |
Loads the OpenAPI document and validates traffic against it. |
internal/platform/errs |
Application errors with stable codes, independent of HTTP. |
internal/platform/logging |
Builds the logger and carries a request-scoped logger in the context. |
internal/platform/tracing |
OpenTelemetry setup. |
internal/platform/version |
Build metadata. |
Rules¶
A feature owns everything about its resource. internal/tasks has four files: the
model (task.go), the business rules (service.go), the SQL (repository.go) and the
HTTP endpoints (handler.go). Deleting the directory deletes the feature; the only other
places that mention it are the composition root, its migration and its part of the
OpenAPI document.
Features do not import each other. users and tasks depend on auth and on the
platform, never on one another. A task belongs to a user through a foreign key; when the
owner does not exist, the database rejects the insert and the repository reports it as
invalid input. There is no call from tasks into users.
auth does not know how users are stored. It declares the interface it needs and
users.Service implements it:
// UserDirectory is what authentication needs to know about users.
type UserDirectory interface {
// Authenticate verifies a username and password.
Authenticate(ctx context.Context, username string, password string) (Identity, error)
// Identity returns the current identity of a user. It is called on every
// authenticated request, so role changes and deletions apply immediately.
Identity(ctx context.Context, userID int64) (Identity, error)
}
This keeps the import direction users → auth and makes the middleware testable with an
in-memory directory.
Services depend on interfaces they declare. Each service defines the Store it needs
next to its own code; the repository satisfies it. The service does not import
database/sql.
Only internal/app knows every package. Construction happens in app.New and routing
in routes(). Nothing registers itself through init functions, with one exception: each
database driver registers itself in the driver registry, so that removing a backend is
removing a file.
Errors carry a code, not a status. Services and repositories return errs values such
as errs.NotFound. The mapping to HTTP statuses lives in httpx. See Errors.
The contract is the source of truth. api/openapi.yaml is validated at startup, served
at /openapi.yaml, used to validate requests, and compared with the router by a test. See
API conventions.
Layers inside a feature¶
flowchart LR
H["handler.go<br>decode, authorize, encode"] --> S["service.go<br>validate, apply rules"]
S --> R["repository.go<br>SQL"]
R --> DB[(database)]
| Layer | Does | Does not |
|---|---|---|
| Handler | Reads path, query and body; checks who the caller is and what they may touch; writes JSON, ETag and errors. |
Contain business rules or SQL. |
| Service | Normalises and validates input, applies the rules of the resource. | Know about HTTP or about the caller's role. |
| Repository | Runs SQL and maps driver errors to application errors. | Decide anything. |
Authorization sits in the handler because it depends on the caller, which is an HTTP
concern here. A handler loads the resource, calls Identity.Authorize(ownerID) and only
then passes the resource to the service.
Lifecycle of the process¶
cmd/apiloads the configuration. Every invalid variable is reported and the process exits before doing anything else.app.Newsets up tracing when enabled, opens the database, applies migrations whenDATABASE_AUTO_MIGRATEis true, builds the components, creates the bootstrap administrator when configured, and loads the contract.App.Runstarts the API server and, unlessADMIN_PORT=0, the admin server.- On
SIGINTorSIGTERM, readiness starts failing, both servers stop accepting connections and wait for in-flight requests up toAPP_SHUTDOWN_TIMEOUT, and the database and the tracer are closed.