API Backend (Go)

Run the Go service that validates Laravel Sanctum tokens and serves protected mobile resources for Flutter.

What is implemented

The generated api-backend/ is a Chi-based Go service for Account projects. It provides:

GET /health liveness and GET /api/v1/health readiness.
Typed environment config for HTTP, PostgreSQL, Redis, CORS, body limits, proxies, and Sanctum expiry.
Recovery, request IDs, CORS/security headers, body limits, rate limits, and optional request logging.
Sanctum token lookup/ability checks against Laravel's personal_access_tokens table.
Protected /api/v1/app/* handlers and Laravel-compatible response resources.

Go does not issue auth tokens, run Laravel migrations, own uploads/webhooks, revoke sessions/delete accounts, or send admin notification broadcasts. Keep those routes on Laravel.

Shared routes served by Go

Method	Route	Guard/behavior
`GET`	`/api/v1/app/me`	`user:read`
`POST`	`/api/v1/app/device-tokens`	`user:update`
`PUT`	`/api/v1/app/users/{uuid}`	`user:update`
`GET`	`/api/v1/app/security/authlogs`	`security:read`
`GET`	`/api/v1/app/security/sessions`	`security:read`
`GET`	`/api/v1/app/help-center*`	Authenticated reads
`POST/GET`	`/api/v1/app/help-center/feedback`	Feedback abilities/quotas
`GET/PUT/DELETE`	`/api/v1/app/notifications*`	Notification abilities
`GET/PUT`	`/api/v1/app/preferences`	Preference abilities
`GET/PUT`	`/api/v1/app/notifications/preferences`	Preference abilities
`GET`	`/api/v1/app/billing/entitlements`	`billing:read`

Go intentionally returns 404 for unsupported sync routes and admin send/broadcast routes.

Local setup

Requirements: Go 1.26.5 or newer, plus access to the shared Laravel DB/Redis.

cd api-backend
cp .env.example .env
# Match Laravel's DB_*, REDIS_*, RATE_LIMIT_NAMESPACE, and LARAVEL_URL.
go mod download
go run ./cmd/api

curl http://localhost:8080/health
curl http://localhost:8080/api/v1/health

Set DB_ENABLED=false for a process-only health check before the shared database exists. With DB enabled but unreachable, liveness stays healthy while readiness returns 503.

Docker modes

compose.dev.yaml is a standalone smoke-test stack for PostgreSQL, Redis, and Go:

docker compose -f compose.dev.yaml up --build

compose.yaml is a production-style service definition that expects external web/shared networks and .env.production. CLI-generated projects do not include or publish the repository-level docker/infra/docker/proxy directories. Provide those networks and any database, Redis, and reverse-proxy services through your own customer-managed infrastructure.

Schema and parity

Laravel migrations are the schema source of truth. When they change:

Migrate a temporary Laravel database.
Refresh the Go schema snapshot and SQL queries.
Run sqlc generate.
Compare Flutter responses/error envelopes with Laravel before switching the gateway.

Do not add Go migrations or edit generated sqlc files manually.

Verification

gofmt -l .
go vet ./...
go test ./...
go test -race ./...

Route /api/v1/app/* to Go only after validating abilities, request validation, response fields/timestamps, error envelopes, and side effects against Laravel compatibility mode.