saldra-api

Production-oriented Go API skeleton for a Norwegian accounting backend (PostgreSQL, Chi, pgx, sqlc).

Prerequisites

• Go 1.23+
• Docker (optional, for Compose and for make sqlc-docker)

Local run

Docker Compose (API + PostgreSQL)

1. Copy .env.example to .env if you want Compose or shell to pick up the same values (optional; the compose file sets the essentials for the api service).

2. Start Postgres, the API, and the background worker:

   docker compose up --build

   Or: make docker-up (same as docker compose up --build). The worker service runs cmd/worker against the same database; scale it or leave it at one replica as needed.

   Next.js web + auth DB in the same Compose: if you also have the saldra frontend repo as a sibling directory, use its docker-compose.yml (build context ../saldra-api) instead of this file’s stack to avoid two Postgres instances on the same ports.

3. Probes:

   • Liveness — GET http://localhost:8080/health/live
   • Readiness (DB ping via sqlc) — GET http://localhost:8080/health/ready

Run the binary on the host

With PostgreSQL reachable (for example Compose running only the postgres service, or a local install):

# Load variables from .env into your shell (optional)
set -a && source .env && set +a

make build
./bin/api

Faster iteration without writing bin/api:

set -a && source .env && set +a
make run-dev

For readable logs in the terminal, set LOG_FORMAT=text in .env or your environment.

Configuration is read from environment variables; see .env.example for names and defaults. DATABASE_URL is required.

Makefile

Target	Description
make tidy	go mod tidy
make fmt	go fmt ./...
make vet	go vet ./...
make test	Run tests
make build	Build bin/api
make worker	Build bin/worker (background jobs)
make run	Build and run bin/api
make run-dev	go run ./cmd/api (no bin/ step)
make sqlc	Regenerate internal/store/db (local sqlc)
make sqlc-docker	Same, using the sqlc/sqlc image
make docker-up / make docker-down	Compose stack

Implementation notes

• internal/app/bootstrap — Constructs the database pool, sqlc queries, HTTP router, and http.Server. Keeps cmd/api and signal/shutdown logic in internal/app small as the system grows.
• Logging — log/slog with JSON by default (LOG_FORMAT=json); text is intended for local development.
• HTTP — Chi with client IP, panic recovery, request IDs, structured access logs, and a configurable per-request timeout.
• Shutdown — SIGINT/SIGTERM stop new work; http.Server.Shutdown respects SHUTDOWN_TIMEOUT, then the pool closes.

Versioned JSON APIs under /v1 require authentication. Until OAuth/JWT is wired, send the demo principal id:

X-Principal-ID: 00000000-0000-0000-0000-000000000002 (see migration seed for demo@example.com and membership on the demo org).

See ARCHITECTURE.md for layering, tenants, and RBAC. For versioning, pagination, idempotency, and integration clients, see docs/API_GUIDELINES.md and openapi/openapi.yaml.