# Go Backend Blueprint (Iteration Draft)

## Chosen Stack

- **Framework:** Gin
- **Migrations:** Goose (SQL-only)
- **DB Access:** SQLC (no ORM), package per bounded context
- **PostgreSQL Driver/Pool:** pgx/v5 + pgxpool
- **Logging:** Uber Zap (structured logs)
- **Health Probes:** liveness/readiness endpoints
- **API Docs:** OpenAPI (for frontend TypeScript type generation)
- **Deployment:** Docker Compose on self-hosted hardware

---

## Architecture Direction

### Layering

- `cmd/api` - application entrypoint and dependency wiring
- `internal/http` - Gin router, handlers, middleware
- `internal/service` - business logic + transaction boundaries
- `internal/db/<context>` - SQLC-generated code by bounded context
- `internal/store` - shared DB/Tx helpers
- `internal/auth` - JWT validation + role guards
- `internal/config` - env configuration loading
- `migrations/` - Goose SQL migration files
- `api/openapi/` - OpenAPI spec + generated artifacts

### Transaction Strategy

- Handlers stay thin.
- Service layer owns DB transactions.
- SQLC queries are called with either pool or tx using `DBTX` interfaces.
- No transaction logic in handlers.

---

## API and Runtime

### API Shape

- REST JSON API
- Possible future WebSocket support for interactive features
- Suggested versioning: `/api/v1`

### Health Endpoints

- `GET /health/live` - process is alive
- `GET /health/ready` - DB ping succeeds (and optionally migration version check)

### Logging

- Zap JSON logs
- Correlation/request ID in middleware
- Structured error logging from middleware and service boundaries

---

## Database and Migrations

### Goose

- SQL-only migrations
- Keep up/down migration scripts
- Run on startup in non-prod optional, required in CI/CD/deploy step

### SQLC

- Generate one package per bounded context (similar to Spring repository modules)
- Keep SQL in context directories (`query.sql`, `models.sql` style)
- Service layer composes multiple repositories when needed

---

## Testing Approach (Beginner-Friendly)

### Phase 1 (Recommended Start)

- Unit tests for pure service logic (no DB)
- Integration tests for SQLC repositories with real Postgres via Docker

### Phase 2

- HTTP handler tests with `httptest`
- Auth middleware tests

### Phase 3

- Minimal end-to-end happy path tests

---

## OpenAPI + Frontend Type Generation

- Keep spec in repo at `api/openapi/openapi.yaml`
- Generate frontend TypeScript types from OpenAPI (e.g. `openapi-typescript`)
- Optionally serve Swagger UI from backend

---

## Deployment

- Docker Compose for app + postgres
- Healthcheck in compose should target readiness endpoint
- Env-based configuration (`.env`, `.env.example`)

---

## Pending Decisions

1. JWT signing:
   - HS256 shared secret (simple)
   - RS256 keypair (better long-term)

2. Token model:
   - Access token only
   - Access + refresh token

3. Initial roles:
   - USER / ADMIN
   - USER / MODERATOR / ADMIN

4. OpenAPI workflow:
   - Contract-first (spec first)
   - Code-first annotations

5. CORS policy:
   - Allowed frontend origins in dev/prod

6. Schema strategy:
   - Single schema (`public`) confirmation

7. Initial bounded contexts:
   - e.g. `auth`, `users`, `rooms` (or your domain names)

---

## Iteration Notes

- This file is intentionally a working draft.
- We will refine decisions and turn this into a concrete implementation checklist.