Developer Guide

This section is for contributors and developers who want to modify, extend, or understand the internals of AI Gateway. Whether you are adding a new Terraform module, fixing a bug, or improving the CI pipeline, start here.

What This Section Covers

Page	Description
Contributing	Fork-and-branch workflow, commit conventions, PR requirements, and the full mise task reference
Architecture	System architecture with Mermaid diagrams, module boundaries, request and auth flows
ADR Index	All Architecture Decision Records with summaries and rationale
CI/CD Pipeline	The 6-job CI pipeline, additional workflows, release process, and Dependabot config
Code Quality	Ruff, pyright, pytest, Terraform quality gates, git hooks, and the 12-tool security scanning stack

Quick Development Setup

# 1. Clone the repository
git clone git@github.com:theagenticguy/ai-gateway.git
cd ai-gateway

# 2. Install all tool versions (Python 3.13, Terraform 1.10.5, lefthook, etc.)
mise install

# 3. Install Python dependencies and git hooks
mise run install
# (equivalent to: uv sync && lefthook install)

# 4. Verify everything works
mise run ci

One-command setup

mise run install handles both Python dependency installation (uv sync) and git hook registration (lefthook install) in a single step.

After setup, your environment includes:

• Python 3.13 with a .venv managed by uv
• Terraform 1.10.5 with all providers pinned in versions.tf
• lefthook git hooks (pre-commit, pre-push, commit-msg)
• Security tools: trivy, hadolint, gitleaks, checkov (all installed via mise)

Project Layout

ai-gateway/
  adr/                    # Architecture Decision Records (001-017)
  docs/                   # Documentation source (Astro Starlight)
  infrastructure/         # Terraform root module + 17 child modules
    modules/
      admin_api/          # API Gateway REST API for admin endpoints
      api_foundation/     # Control-plane stage, usage plans, gwcore alarms
      appconfig/          # AppConfig for dynamic configuration
      audit_log/          # Kinesis Firehose + S3 Parquet audit trail
      audit_pipeline/     # Kinesis Firehose → Apache Iceberg audit sink
      auth/               # Cognito, JWT listener
      budgets/            # Budget management and enforcement
      chargeback/         # Chargeback reporting
      clients/            # Per-team Cognito app clients
      compute/            # ECS, ECR, IAM, Secrets Manager, agentgateway config
      cost_attribution/   # Token usage and cost metrics pipeline
      guardrails/         # Bedrock Guardrails resource (inline ApplyGuardrail)
      inspector/          # Amazon Inspector scanning
      networking/         # VPC, ALB, WAF
      observability/      # KMS, CloudWatch log groups, dashboard
      routing/            # Dynamic routing config (renders agentgateway backend)
      team_registration/  # Self-service team onboarding
    environments/         # Per-environment tfvars (dev, prod)
  scripts/                # Operational scripts (token retrieval, CW queries)
  .github/
    workflows/            # CI/CD, CodeQL, dependency-review, release, scorecard, docs
    dependabot.yml        # Automated dependency updates
    CODEOWNERS            # Review requirements
    SECURITY.md           # Vulnerability reporting policy
  mise.toml               # Tool versions + 25+ project tasks
  lefthook.yml            # Git hook definitions
  pyproject.toml          # Python project metadata + dev dependencies
  ruff.toml               # Linter/formatter configuration
  pyrightconfig.json      # Type checker configuration
  docs/astro.config.mjs   # Documentation site configuration