web/docs/GETTING_STARTED.md

Getting started

Gamertan Web Foundations is adopted one boundary at a time. Start with the smallest package that solves a problem the application actually has; do not install an imagined framework lifecycle around it.

Choose a first slice

Application need	Begin with	What remains application-owned
Request IDs and trustworthy client addresses	requestmeta	Proxy configuration and operational logs
Bounded structured request evidence	requestmeta, requestlog	Route names, sensitive-field policy, rotation, retention, and access
Browser and HTTP safety primitives	requestmeta, websec	Exact CSP, route authorization, and response policy
Persistent request-abuse decisions	requestmeta, abuse	Route classification, storage, appeals, and operator policy
Users, credentials, permissions, and sessions	auth	Roles, permissions, login UX, and account policy
Secure browser cookies around auth	authhttp	Login routes, redirects, pages, and authorization decisions
SQLite persistence for auth	authsqlite	Database placement, backup, migration approval, and recovery
One account across organizations and teams	organizations, authsqlite	Invitation UX, organization naming, and lifecycle policy
Organization-scoped authorization	access, authsqlite	Role definitions, resource ownership, and route enforcement
Aggregate projections over request records	analytics	Collection policy, access control, report UI, and retention

The packages are ordinary Go imports. Pin the current preview and verify its module checksum:

go get gamertan.com/web/requestmeta@v0.1.0-preview.2
go mod verify

Preserve middleware order

Packages that consume request metadata must run inside the resolver. Build the handler from the application outward; the final resolver assignment becomes the first middleware to receive a request:

var handler http.Handler = router
handler = requestlog.Middleware(sink, logPolicy)(handler)
handler = websec.Headers(headerPolicy)(handler)
handler = resolver.Middleware(handler)

The complete, copyable composition is in starters/basic. It binds to loopback, shuts down gracefully, and keeps request logging optional.

Configure trusted proxy networks narrowly. A forwarding header is not evidence by itself; it becomes usable only when the immediate peer and skipped proxy hops satisfy the resolver's trust policy. Metadata, authentication, or storage failures that affect security decisions should stop the request rather than quietly changing identity or policy.

Add HTML without merging responsibilities

Handlers should convert request and service state into typed display data. They may then render those values with any HTML system. Gamertan's preferred companion is Sandwich Hime, whose generated components keep templates typed while leaving this middleware stack and the net/http application in control.

Verify the application boundary

After adopting a package:

go mod verify
go test ./...
go test -race ./...
go vet ./...
go build ./...

Test the composed handler with httptest, not only the package in isolation. Include a normal request, malformed or spoofed metadata, a downstream failure, and the application's intended response headers. Existing applications should follow the differential and rollback sequence in ADOPTION.md.

Deeper tutorials for accounts, analytics, and persistent abuse policy will be written after multiple application migrations have validated those seams. The preview documentation describes demonstrated contracts rather than prescribing an unfinished application framework.

See Organizations and scoped access before storing tenant data. In particular, do not interpret a platform role as permission to inspect an organization's records.