Repository navigation
Architecture Go
The recommended candidate. This page describes how the language-neutral design on Architecture Overview would be built in Go. It is a design; nothing is implemented yet. Versions are those current at the time of evaluation and will be refreshed when work starts.
In short: one static binary built from net/http + huma v2 on chi v5 + pgx v5 + sqlc, organised as a hexagon around the domain. Keys, limits, quotas, priority admission and cache are in-process. The 2 second deadline is enforced with pgx's automatic cancel request plus a per-transaction statement timeout. Estimated 25–45 MB resident memory; image target 20 MB or less.
| Concern | Choice | Why | Alternatives rejected |
|---|---|---|---|
| HTTP | standard library net/http
|
timeouts, response controller, no framework runtime | fasthttp (not net/http-compatible), Gin and Echo (OpenAPI bolted on) |
| Router | chi v5 | middleware groups (public, admin, operations); huma adapter | the standard mux (weaker grouping) |
| API and OpenAPI 3.1 | huma v2 | code-first 3.1 from Go types, validation from tags, RFC 9457 model, operation extensions | ogen and oapi-codegen (spec-first: a second source of truth), swaggo (older OpenAPI) |
| Driver | pgx v5 with pgxpool | real cancel request on context end; statement cache; batch and pipeline; query tracer |
database/sql with lib/pq (maintenance mode), GORM and ent (ORMs fight "views are the contract") |
| Queries | sqlc | typed Go from .sql, checked against the contract stub at generate time |
squirrel (no check), jet (needs a live database) |
| Access-store migrations | goose, embedded plain SQL | simple, custom version table | golang-migrate, atlas |
| Configuration | koanf v2 + validator v10 | layering, unknown keys refused, bounds in tags, docs by reflection | viper (lower-cases keys, ignores unknowns), env-only libraries |
| Rate limiting | golang.org/x/time/rate |
Reserve() gives an exact Retry-After
|
Redis-shaped limiters |
| Admission | own small package | priority, reserved shares, aging, wait estimate (the standard semaphore is FIFO only) | — |
| Cache | otter v2 | byte weigher, per-entry expiry, loader with single-flight | golang-lru (no expiry or weigher), ristretto (may drop writes) |
| Compression | klauspost/compress gzhttp + brotli | fast, minimum size, correct ETag suffixing | standard gzip |
| Logs | standard log/slog
|
no dependency; attribute redaction hook | zap, zerolog |
| Tracing and metrics | OpenTelemetry Go, otelhttp, otelpgx; Prometheus client | standard | — |
| Geometry | go-geom | polyline decoding only; heavy geometry stays in PostGIS | orb |
| Tests |
testing, testify, testcontainers-go (PostGIS), native fuzzing |
— | — |
| Quality | golangci-lint (depguard, gosec, forbidigo), govulncheck, oasdiff, Spectral | — | — |
| Documentation | Scalar (static) + Astro Starlight guide | — | Redoc |
viafrei-api/
├── cmd/viafrei-api/ # serve | migrate | keys | usage | config {check,show,docs} | openapi | version
├── internal/
│ ├── domain/ # pure: standard library + geometry type only
│ │ ├── shared/ provenance/ places/ roads/ energy/ parking/ transit/ accessibility/ weather/ rules/
│ │ └── access/ # key, plan, scope, tier, the licence decision (a pure function)
│ ├── app/ # one package per feature; ports only
│ ├── adapters/
│ │ ├── store/ # the ONLY code that knows the read contract (sqlc output, mapping tables, deadline execution)
│ │ ├── accessstore/ # keys, plans, audit, usage + migrations
│ │ ├── cache/ # result cache, freshness versions
│ │ └── httpapi/ # operations, DTOs, problems, GeoJSON, middleware
│ └── runtime/ # config, admission, ratelimit, metering, telemetry, lifecycle
├── contract/ # the read-contract file and stub, delivered by the version-sync pull request
├── api/openapi.json docs/ bench/ test/
└── Dockerfile sqlc.yaml .golangci.yml
Dependency direction: cmd → adapters → app → domain, and adapters → runtime. A depguard rule forbids the driver, the HTTP framework and the adapters inside domain and app.
// domain/roads/ports.go
type SituationReader interface {
InCorridor(ctx context.Context, c Corridor, w shared.TimeWindow, f Filter) ([]RoadSituation, provenance.Set, error)
History(ctx context.Context, r RoadRef, w shared.TimeWindow, cur Cursor, n int) (Page[Observation], provenance.Set, error)
}pgx is configured so that, when a request's context ends, it sends a PostgreSQL cancel request at once and gives the connection a short grace period:
cfg.ConnConfig.BuildContextWatcherHandler = func(c *pgconn.PgConn) ctxwatch.Handler {
return &pgconn.CancelRequestContextWatcherHandler{Conn: c, CancelRequestDelay: 0, DeadlineDelay: conf.DB.CancelGrace}
}- Each read runs as one batch: a read-only transaction,
set_config('statement_timeout', <remaining ms>, true), the query limited to the allowed source families, commit. The server therefore stops on its own even if the client-side cancel were lost. - After release, a connection that is not idle is destroyed instead of being returned to the pool.
- To confirm in the benchmark: the single-round-trip batch against an explicit transaction.
crypto/hmac with SHA-256 and constant-time hmac.Equal; secrets from crypto/rand; a small, fuzzed base62 codec. The key cache is an otter cache whose loader collapses concurrent first lookups into one. Revocations arrive through a PostgreSQL notification on a dedicated connection and evict the key at once.
-
Rate limit: one
rate.Limiterper key, held in a cache with idle expiry. IfReserve()reports a delay, the reservation is cancelled and the answer is429withRetry-Afterrounded up from the delay. -
Admission: a mutex-guarded structure with three queues of waiters.
Acquiregrants, enqueues and waits on a channel or the context (removing itself on cancel), or refuses by estimate.Releaseruns the dispatch loop and updates the moving average of service time. Tested with the race detector and with a deterministic simulation on a fake clock. -
Composed features:
errgroupwith a concurrency limit equal to the permits granted; each part has its own sub-deadline, and its error becomes the part's status. - Metering: atomic counters in a map, swapped and flushed by a ticker as one batched upsert.
otter with a byte weigher and per-entry expiry; xxh3 for ETag hashing; gzhttp suffixes ETags of compressed variants correctly.
| Memory item (estimate) | Size |
|---|---|
| Runtime and binary | ~10–14 MB idle |
| Result cache | 16 MiB (configurable) |
| Key cache | a few MB |
| Connections | about 1 MB each, client side |
Estimated steady state 25–45 MB; container limit 128 MiB, with the Go soft memory limit set below it so the garbage collector tightens before the kernel intervenes.
- huma generates OpenAPI 3.1, served at
/openapi.json. Every operation is registered with its id, summary, description, tags, security requirement and the extensions for scope, source families and MCP counterpart. - A project
problemtype implements huma's status-error interface and emitsapplication/problem+jsonwith the project'stypeURIs. - Geometry passes through as raw JSON while the schema is still declared from DTO types.
-
application/geo+jsonis registered as a second response content type.
The configuration struct is the declaration: tags carry the key, default, bounds and description. Defaults, then a YAML file, then environment variables; every loaded key is checked against the set reflected from the struct; all violations are printed together. Secret fields use a type whose string, JSON and log forms are <redacted>. config docs generates the reference by reflection. See Configuration.
- testcontainers-go with PostGIS for mapping, role, cancellation and query-plan tests; httptest and humatest for handlers; libopenapi-validator on every recorded response; Schemathesis against the booted container.
- Native
go test -fuzzfor cursors, keys, polylines, parameters and the YAML loader. -
go test -race -shuffle=on;-coverpkg=./...in the unit and integration runs, and a boot smoke (go build -cover,GOCOVERDIR,go tool covdata textfmt) for everymain; the three profiles are merged byinternal/testkit/covergate, which fails any package below 100 % (TST-001). Branches that cannot fail by construction go throughinternal/invariant(Must,Check) instead of an unreachable error return. - golangci-lint, govulncheck, CodeQL for Go.
- release-please with the Go release type.
Multi-stage build, CGO_ENABLED=0, trimmed and stripped, version information injected at build time; final stage distroless/static as a non-root user, pinned by digest. Image target 20 MB or less compressed; CI scans the layers for secrets.
| Risk | Mitigation |
|---|---|
| A second toolchain beside the platform | self-contained repository with its own CI; the contract file is the only coupling |
| AI-agent fluency | high for Go; strict linting, small packages, generated plumbing (sqlc, huma) |
| huma has a small maintainer team | standard OpenAPI output and plain handler functions make a move mechanical |
| Garbage collection under a tight limit | Go soft memory limit, byte-bounded cache, verified in the benchmark |
| Licence matrix not yet signed off | the gate defaults to deny; families are enabled one at a time |
Estimated somewhat less than the Rust design and close to the TypeScript design, which is faster for the first features and slower for the store adapter's cancellation path. See Stack Comparison.
huma https://huma.rocks · chi https://pkg.go.dev/github.com/go-chi/chi/v5 · pgx https://pkg.go.dev/github.com/jackc/pgx/v5 · sqlc https://docs.sqlc.dev · goose https://pressly.github.io/goose/ · koanf https://github.com/knadh/koanf · validator https://pkg.go.dev/github.com/go-playground/validator/v10 · rate https://pkg.go.dev/golang.org/x/time/rate · otter https://maypok86.github.io/otter/ · gzhttp https://pkg.go.dev/github.com/klauspost/compress/gzhttp · OpenTelemetry Go https://opentelemetry.io/docs/languages/go/ · otelpgx https://github.com/exaring/otelpgx · testcontainers-go https://golang.testcontainers.org/modules/postgres/ · Go fuzzing https://go.dev/doc/security/fuzz/ · libopenapi-validator https://github.com/pb33f/libopenapi-validator · golangci-lint https://golangci-lint.run · govulncheck https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck · distroless https://github.com/GoogleContainerTools/distroless · PostgreSQL cancel protocol https://www.postgresql.org/docs/16/protocol-flow.html#PROTOCOL-FLOW-CANCELING-REQUESTS
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference