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

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 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