# Checklist: Adding a New GraphQL Field (End-to-End)

## 1. OWS Service (if new data from Snowflake)

- [ ] Write/modify Snowflake query (SQL template or ORM model)
- [ ] Add field to Marshmallow response schema
- [ ] Add/update REST endpoint in handler
- [ ] Add Redis caching with appropriate TTL
- [ ] Write unit test with mocked Snowflake
- [ ] Run `make test_unit && make lint`

## 2. GraphQL Subgraph

- [ ] Add connector method for OWS endpoint (if new)
  - [ ] Zod schema for response validation
  - [ ] DataLoader factory with `cacheKeyFn`
  - [ ] Register DataSource in context
- [ ] Add field to `.graphql` schema file
- [ ] Create mapper `*Key` interface (if new type)
- [ ] Register mapper in codegen config (if new type)
- [ ] Write resolver (`satisfies Partial<QueryResolvers>` or `<TypeName>Resolvers`)
- [ ] Run `yarn generate:types`
- [ ] Write unit tests (Zod schema, resolver, DataLoader)
- [ ] Run `yarn test:unit && yarn lint`

## 3. GraphQL Router (usually no changes)

- [ ] Verify federation composition: `cd graphql-router && make supergraph`
- [ ] If composition fails, check `@key`, `@shareable`, `@external` directives

## 4. Frontend

- [ ] Add field to `.gql` query file in `src/apollo/queries/<domain>/`
- [ ] Run `yarn generate:types`
- [ ] Update `.ts` wrapper (data transformation if needed)
- [ ] Use field in component
- [ ] Write component test
- [ ] Run `yarn test:unit && yarn lint`

## Deployment Order

1. OWS service (data layer) — must be deployed first
2. GraphQL subgraph — consumes new OWS endpoint
3. Router — automatic (federation recomposes)
4. Frontend — consumes new GraphQL field

## Feature Flag Strategy

If deploying incrementally:
1. Add feature flag in Split.io
2. Gate OWS endpoint behind flag (optional)
3. Gate GraphQL resolver behind flag
4. Gate frontend UI behind `useIdentity().features['flag']`
5. Enable progressively: QA → UAT → Prod