# Router Service Agent

Expert agent for working in the `graphql-router` Rust service.

## Context

You are working in the Apollo Federation gateway built with Apollo Router (Rust). This service routes all frontend GraphQL queries to the appropriate federated subgraphs.

## Architecture

- **Apollo Router 2.12.1** with custom Rust plugins
- **Rust 1.94** (pinned via `rust-toolchain.toml`)
- **17 federated subgraphs** composed into a single supergraph
- **Tower middleware** for request/response processing
- **Two custom plugins**: auth enforcement + client name validation

## Key Areas

### Plugin Development

Plugins use Apollo Router's `register_plugin!` macro:

```rust
register_plugin!("namespace", "plugin_name", PluginStruct);
```

Plugin lifecycle:
1. Implement `Plugin` trait
2. Define configuration struct (with `schemars::JsonSchema` + `serde::Deserialize`)
3. Override `supergraph_service()` to wrap the Tower service
4. Map requests/responses in the service wrapper

### Supergraph Management

```bash
make supergraph             # Recompose from all 17 subgraphs
```

The script in `scripts/generate-supergraph.sh`:
1. Introspects each subgraph via Rover CLI
2. Stores schemas in `./subgraphs/`
3. Generates `supergraph.yaml` configuration
4. Runs `rover supergraph compose`

### Adding a New Subgraph

1. Add entry to `scripts/generate-supergraph.sh` (name + QA URL)
2. Run `make supergraph`
3. Add subgraph URL to `config-qa.yaml`, `config-uat.yaml`, `config-prod.yaml`
4. Test with `make dev`

### Configuration

Environment-specific YAML files:
- `config-qa.yaml` — introspection enabled, sandbox enabled
- `config-uat.yaml` — intermediate settings
- `config-prod.yaml` — introspection disabled, no sandbox

Key settings: supergraph listener, header propagation, traffic shaping (65s timeout), telemetry (OTLP to Datadog).

## Commands

```bash
make dev            # Run with hot-reload
make test           # cargo test
make lint           # cargo clippy (warnings = errors)
make fmt            # cargo fmt
make build          # cargo build
make supergraph     # Recompose federation supergraph
make check          # cargo check (fast compile check)
```

## Common Mistakes to Avoid

- Do NOT modify supergraph.graphql directly — it's generated by `make supergraph`
- Do NOT forget to update ALL environment configs when adding subgraphs
- Do NOT remove header propagation rules without understanding downstream impact
- Do NOT use `unwrap()` in plugin code — use `anyhow` error handling
- Always run `make lint` before committing — clippy warnings are errors
- Always test with `make dev` before pushing — hot-reload validates config