Local Development

The repo is a monorepo with four buildable components: a shared Python library, the backend Lambda handlers, the Next.js console, and the Go CLI helper.

Prerequisites

Python 3.13 + uv
Node.js 20+ and npm
Go 1.23+
OpenTofu (validation only — never run plan/apply locally)

Backend (Python Lambda + shared library)


cd backend && uv sync          # backend installs shared as an editable dep
cd backend && uv run pytest
cd backend && uv run pytest tests/test_proxy.py -k "test_auth"
cd backend && uv run ruff check --fix .
 
cd shared && uv sync && uv run pytest

Tests use moto to mock DynamoDB, KMS, S3, STS, and SES — no real AWS credentials needed. conftest.py sets POWERTOOLS_TRACE_DISABLED=true so X-Ray is disabled locally.

Frontend (Next.js console)


cd frontend && npm install
cd frontend && npm run dev      # hot reload on http://localhost:3000
cd frontend && npm run build    # static export
cd frontend && npm run lint
cd frontend && npm test         # Vitest

The console reads .env.local in development:


NEXT_PUBLIC_API_URL=https://api.<stage>.<domain>
NEXT_PUBLIC_COGNITO_DOMAIN=auth.<stage>.<domain>
NEXT_PUBLIC_COGNITO_CLIENT_ID=<console-app-client-id>
NEXT_PUBLIC_COGNITO_REDIRECT_URI=http://localhost:3000/

Go CLI (`agent-runner-auth`)


cd tools/agent-runner-auth
go build -o agent-runner-auth .
go test ./...

Backend field names use snake_case; frontend type properties use camelCase. Conversion happens at the HTTP boundary via camelizeKeys() / snakelizeKeys() in frontend/src/lib/api.ts — never hardcode snake_case in frontend request bodies.

This documentation site itself lives in docs-site/ — see Deployment → Docs Site.