42 lines
1.8 KiB
Markdown
42 lines
1.8 KiB
Markdown
# 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
|