# CLAUDE.md — graphql-user

This file provides guidance for AI assistants working in the graphql-user repository.

## Project Overview

**graphql-user** is an Apollo GraphQL server (TypeScript, Node.js) that manages user data for the Orchard Insights platform. It handles user profiles, permissions, account relationships, and notification preferences using Neo4j as the primary data store. Part of the Apollo Federation supergraph served via `graphql-router`.

## Essential Commands

```bash
# Development
yarn start                  # Dev server with hot-reload (ts-node + nodemon)

# Build
yarn build                  # Production build (tsc + copy schema + copy cypher files)

# Testing
yarn test                   # Full suite: format check + lint + unit tests
yarn test:unit              # Jest unit tests only
yarn test:unit:watch        # Watch mode
yarn test:integration       # Integration tests (requires Neo4j, --runInBand)
yarn test:types             # TypeScript type checking (no emit)

# Linting & Formatting
yarn lint                   # ESLint + GraphQL schema linting
yarn lint:fix               # Auto-fix lint issues
yarn format                 # Prettier formatting
yarn format:check           # Check formatting only

# Code Generation
yarn generate:types         # Generate TypeScript types from GraphQL schema
```

To run a single test file:
```bash
yarn test:unit -- --testPathPattern="path/to/test"
```

## Setup

Copy `.env.shadow` to `.env` before running locally: `cp .env.shadow .env`

## Architecture

### Tech Stack

| Layer | Technology |
|-------|-----------|
| Framework | Apollo Server 5.0.0 (with @theorchard/graphql-server 4.0.1 wrapper) |
| Language | TypeScript 5.9, Node.js >=20.11.1 |
| GraphQL | Schema-first, Apollo Federation, Code Generator v5 |
| Primary DB | Neo4j (via @theorchard/connector-neo4j 2.2, @theorchard/datasource-neo4j 4.0) |
| Caching | Redis via Keyv + @keyv/redis + response cache plugin |
| Validation | Zod 4.1 |
| Analytics | Segment (@segment/analytics-node 2.1) |
| Testing | Jest 29.7 + ts-jest |
| Linting | ESLint 9.14 (@theorchard/eslint-config-ts-prettier) |
| Formatting | Prettier 3.2 |
| Observability | Sentry 9.43, Datadog (dd-trace) |
| Feature Flags | Split.io |
| Secrets | AWS Secrets Manager |
| Git Hooks | Husky 9.0 |

### Directory Structure

```
src/
├── connectors/              # DataSource abstraction layer
│   ├── neo4j/               # Neo4j driver + Cypher query execution
│   ├── graphql-router/      # Federation gateway connector
│   ├── ows-account/         # Account service connector
│   ├── ows-pdp/             # PDP service connector
│   ├── ows-permissions/     # Permissions connector
│   ├── ows-users/           # Users service connector
│   ├── ows-notifications/   # Notification service connector
│   └── notifications/       # Custom event handler
├── resolvers/               # GraphQL resolvers
│   ├── mutation/            # Mutation resolvers
│   ├── types/               # Mapper Key interfaces
│   ├── __fixtures__/        # Test fixtures
│   ├── __tests__/
│   └── generated/           # Codegen output (within resolvers)
├── schema/                  # Modular .graphql files
├── cypher/                  # .cypher query files (copied to build)
│   └── country-filter/      # Country-specific queries
├── utils/                   # Shared utilities
│   └── __tests__/
├── constants/               # Application constants
├── __mocks__/               # Jest mocks
├── config.ts                # Environment configuration
└── types.ts                 # Shared TypeScript types

lib/                         # Test helpers
tests/
├── integration/             # Integration tests
└── __tests__/
```

### Data Flow

```
GraphQL Query → Resolver → DataLoader → Neo4j Connector → Neo4j (Cypher)
                    │                  → OWS Connector   → OWS REST API
                    ↑
              Redis cache + Response cache plugin
```

## Key Patterns

### Cypher Query Files

Neo4j queries are written in `.cypher` files under `src/cypher/`. These are copied to the build output. The `country-filter/` subdirectory contains country-specific query variations.

### Segment Analytics

User actions are tracked via Segment (`@segment/analytics-node`). The `SEGMENT_WRITE_KEY` environment variable must be set for event publishing.

### Test Fixtures

Unlike other graphql-* services, this one uses `src/resolvers/__fixtures__/` for structured test data. Use these when writing resolver tests.

### Separate Deploy Service

Docker has a unique `service-deploy` target — a separate build for production testing alongside the standard `service` target.

### Response Cache Plugin

Uses `@apollo/server-plugin-response-cache` for full query response caching. Cache headers and TTL are configured per-query.

### Zod Validation & DataLoader Pattern

Same conventions as other graphql-* services. DataLoader factories, Zod schemas, mapper Key interfaces.

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `ENV` | `qa` / `prod` |
| `NODE_ENV` | `development` / `test` / `production` |
| `PORT` | Server port (default 8088) |
| `NEO4J_URL` | Neo4j Premium bolt URL |
| `NEO4J_USER` | Neo4j username |
| `NEO4J_PASSWORD` | Neo4j password |
| `NEO4J_AURA_URL` | Neo4j Aura bolt URL |
| `NEO4J_AURA_USERNAME` | Neo4j Aura username |
| `NEO4J_AURA_PASSWORD` | Neo4j Aura password |
| `OWS_PDP_URL` | PDP service URL |
| `SEGMENT_WRITE_KEY` | Segment analytics key |
| `CACHE_USE_REDIS` | Enable Redis caching |
| `CACHE_REDIS_*` | Redis connection config |
| `SPLIT_API_KEY` | Split.io feature flag API key |
| `AUTH_ISSUERS` | Auth0 issuer URLs (comma-separated) |

## Testing

- **Unit tests**: `src/**/__tests__/*` — mock Neo4j and OWS connectors
- **Integration tests**: `tests/integration/` — require running Neo4j, run with `--runInBand`
- **Fixtures**: `src/resolvers/__fixtures__/` for structured test data
- **Code generation**: `graphql-integration-codegen` generates types for integration test queries
- **Coverage target**: 80%+

## Docker

Multi-stage build with `.cypher` file copying. Unique dual service targets:
- `service` — Development
- `service-deploy` — Production artifact (port 8081)

Base image: Node 22 (AWS ECR parent). Dev port: 8088, deploy port: 8081.