# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

This is a customized [Apollo Router](https://www.apollographql.com/docs/router/) implementation — a Rust binary wrapping the `apollo-router` crate with two custom plugins. It serves as the federated GraphQL gateway for The Orchard's PDE+GO platform, composing 17 subgraphs into a single API.

## Commands

```bash
make build          # Compile the router binary
make check          # Fast compilation check (no binary output)
make test           # Run unit tests via cargo test
make lint           # Run clippy
make fmt            # Format code
make lint-test      # clippy + cargo test
make ci-lint-test   # Docker-based lint+test (matches CI)
make dev            # Run router in dev mode with hot-reload
make supergraph     # Re-introspect all subgraphs and recompose supergraph.graphql
```

Run a single test:
```bash
cargo test <test_name>
# e.g. cargo test test_valid_jwt
```

Prerequisites: `protobuf` (`brew install protobuf`), Rust 1.95 (pinned in `rust-toolchain.toml`), Rover CLI.

Docker builds require BuildKit and ≥8 GB RAM allocated to Docker (rustc peaks at 4–6 GB compiling `apollo-federation`). On Apple Silicon, Rosetta must be enabled (the parent image is `amd64`).

## Architecture

### Custom Plugins (`src/plugins/`)

The entire `src/` directory is two plugins and a `main.rs` that delegates to `apollo_router::main()`.

**`theorchard.require_apollo_client_name`** (`require_apollo_client_name.rs`)
Rejects requests missing the `Apollographql-Client-Name` header (400 Bad Request). Used for field usage tracking in Apollo Studio and DataDog.

**`pde.auth_enforcement`** (`auth_enforcement/`)
Validates the `Authorization` header. The decision tree lives in `check_auth.rs` (19 unit tests). Outcomes are typed as `AuthResult`: `Ok`, `Warning` (log only), or `Block` (401). Supports three token types:
- **JWT** — validates signature via JWKS endpoint (with caching), checks issuer/audience/expiry
- **HMAC** — validates HMAC-signed tokens
- **Bearer** — pass-through bearer tokens

Configuration maps auth rules (`invalid_jwt`, `expired_jwt`, `hmac_use`, `recipient_mismatch`) to `Ok`/`Warning`/`Block` outcomes per environment. QA configs use `Warning` so invalid tokens are logged but not blocked.

Auth telemetry is emitted to DataDog under a `check_auth` span, tagging auth method, client info, JWT issuer/subject, and HMAC sender/recipient.

### Configuration Files

Each environment has its own config file selected via the `CONFIG_FILE` env var:
- `config-qa.yaml`, `config-qa-internal.yaml`, `config-qa-mcp.yaml`
- `config-uat.yaml`
- `config-prod.yaml`
- `config.yaml` — local dev (gitignored; copy and edit from a QA config)

Router telemetry uses OTLP/HTTP to DataDog. Subgraph headers are all propagated except `x-datadog-*`.

### Supergraph

`supergraph.graphql` (committed) is the composed federated schema used at runtime. Regenerate it with `make supergraph`, which introspects all 17 live subgraphs via `scripts/generate-supergraph.sh` and Rover. Do not hand-edit it. You can also pull it from Apollo Studio:
```bash
rover supergraph fetch graphql-theorchard@qa > supergraph.graphql
```

### Deployment

Three ECS Fargate services per environment (public, internal, MCP). The Jenkinsfile auto-deploys `master` to QA; UAT and Prod require manual promotion. Key env vars at runtime: `APOLLO_KEY`, `APOLLO_GRAPH_REF`, `CONFIG_FILE`.