go-api/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code when working with the go-api repository.

## Project Overview

**go-api** is the REST framework for the Lethean Go ecosystem. It provides a Gin-based HTTP engine with middleware, response envelopes, WebSocket integration, and OpenAPI generation. Subsystems implement the `RouteGroup` interface to register their own endpoints.

- **Module path**: `forge.lthn.ai/core/go-api`
- **Language**: Go 1.25
- **Licence**: EUPL-1.2

See `docs/` for architecture, tool reference, and development guide.

## Build & Test Commands

```bash
go test ./...                       # Run all tests
go test -run TestName ./...         # Run a single test
go test -v -race ./...              # Verbose with race detector
go build ./...                      # Build (library — no main package)
go vet ./...                        # Vet
```

## Authentik Integration

go-api integrates with [Authentik](https://goauthentik.io/) for identity management:

- **Forward auth mode**: Reads `X-authentik-*` headers from Traefik (`TrustedProxy: true`)
- **OIDC mode**: Validates JWT Bearer tokens via OIDC discovery (`Issuer` + `ClientID`)
- **Permissive middleware**: `WithAuthentik()` extracts user but doesn't block requests
- **Route guards**: `RequireAuth()` (401) and `RequireGroup("admins")` (403) for protected routes
- **Coexists with `WithBearerAuth()`** for service-to-service tokens

## Coding Standards

- **UK English** in comments and user-facing strings (colour, organisation, unauthorised)
- **Conventional commits**: `type(scope): description`
- **Co-Author**: `Co-Authored-By: Virgil <virgil@lethean.io>`
- **Error handling**: Return wrapped errors with context, never panic
- **Test naming**: `_Good` (happy path), `_Bad` (expected errors), `_Ugly` (panics/edge cases)
- **Licence**: EUPL-1.2