claude-code-aws-gateway: Instructions file for Claude Code

Claude Code AWS Gateway (CCAG)

Self-hosted API gateway that routes Claude Code through your Amazon Bedrock account. Provides a centralized layer for teams to manage API keys, budgets, rate limits, and OIDC SSO, with a built-in admin portal for observability and configuration.

Build & Test

make build               # Build gateway + CLI
make test                # Unit tests (no dependencies)
make lint                # Format check + clippy
make test-integration    # Integration tests (needs Docker)
make check               # All of the above (what CI runs)
make test-e2e            # E2E HTTP tests (needs AWS credentials)
make dev                 # Start Postgres + gateway (auto-detects free ports)
make dev-seed            # Start with mock analytics data
make dev-reset           # Wipe Postgres and start fresh
make dev-down            # Stop local dev environment

Project Structure

src/
  main.rs              - Gateway entry point, startup, background loops
  cli/                 - CLI operations tool (ccag binary)
    main.rs            - CLI entry point (clap)
    config.rs          - Admin API client, token management
    commands/          - Subcommands: config, keys, users, teams, scim, status, logs
  api/
    mod.rs             - Router, auth endpoints, setup script serving
    handlers.rs        - HTTP handlers (messages, count_tokens, health)
    admin.rs           - Admin API (keys, teams, users, spend, IDPs, endpoints, analytics)
    cli_auth.rs        - Browser-based OIDC login flow
    proxy_login.sh     - apiKeyHelper script (embedded at compile time)
  config/mod.rs        - GatewayConfig, routing prefix auto-detection
  proxy/mod.rs         - GatewayState (shared state)
  auth/
    mod.rs             - In-memory key cache, key validation
    oidc.rs            - Multi-IDP OIDC JWT validation, JWKS caching
    session.rs         - HS256 session token signing/validation
  ratelimit/mod.rs     - Per-key sliding window rate limiter
  db/                  - Postgres pool, migrations, CRUD
    org_analytics.rs   - Cross-org analytics queries (~20 functions)
  spend/mod.rs         - Async spend tracker (buffer + flush)
  budget/              - Budget enforcement and notifications
  endpoint/            - Multi-endpoint pool and routing
    stats.rs           - Per-endpoint rolling-window throttle/error/request counters
  telemetry/mod.rs     - Prometheus metrics, OTLP export
  translate/
    models.rs          - Model ID mapping (Anthropic <-> Bedrock)
    request.rs         - Request translation
    response.rs        - Response normalization
    streaming.rs       - SSE event formatting
  scim/               - SCIM 2.0 provisioning (auth, discovery, users, groups, filter, types)
  websearch/mod.rs     - DuckDuckGo web search interception
static/index.html     - Embedded admin portal SPA (dashboard, analytics, config)
infra/                 - AWS CDK (TypeScript) for ECS Fargate + RDS + CW Dashboard
migrations/            - Postgres schema migrations (auto-run on startup)
docs/
  configuration.md     - Environment variables, runtime settings
  metrics.md           - Metric reference, Prometheus/OTLP config, Grafana examples