zitadel/apps/api/AGENTS.md

ZITADEL API App Guide for AI Agents

Context

The API App (apps/api) is the Nx application target for building and running the Go backend. Most backend implementation lives in internal/, while this project orchestrates build, generate, lint, and test workflows.

Source of Truth

• Go Toolchain: Inspect root go.mod before Go work.
• API Design Contract: Follow API_DESIGN.md for service and resource conventions.
• Domain Logic Location: For implementation details, also read internal/AGENTS.md.

Verified Nx Targets

• Run API (prod profile): pnpm nx run @zitadel/api:prod
• Build: pnpm nx run @zitadel/api:build
• Generate (all): pnpm nx run @zitadel/api:generate
• Install Proto Plugins: pnpm nx run @zitadel/api:generate-install — installs all Go-based proto plugins (buf, protoc-gen-go, protoc-gen-connect-go, protoc-gen-openapiv2, protoc-gen-validate, protoc-gen-authoption, etc.) to .artifacts/bin/$(GOOS)/$(GOARCH)/. Output is Nx-cached; only reruns when plugin versions or local protoc sources change.
• Lint: pnpm nx run @zitadel/api:lint
• Test (all): pnpm nx run @zitadel/api:test
• Test (unit): pnpm nx run @zitadel/api:test-unit
• Test (integration): pnpm nx run @zitadel/api:test-integration

Generation Notes

• @zitadel/api:generate can update generated, tracked files (stubs/assets/statik). Run it intentionally.
• API changes in proto/ often require regenerating API, package, and docs artifacts.
• Proto plugins are installed to .artifacts/bin/ — do not commit these binaries; they are declared as Nx outputs and restored from cache.