From 30edc307af733225d7e975254b33fb66b7452004 Mon Sep 17 00:00:00 2001 From: Brendan Chen Date: Wed, 2 Sep 2026 14:34:16 -0700 Subject: [PATCH] CLAUDE.md -> AGENTS.md --- AGENTS.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 94 +------------------------------------------------ 2 files changed, 104 insertions(+), 93 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cd99b31 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,103 @@ +# CLAUDE.md + +This file provides guidance to all agents when working with code in this repository. + +## Development Commands + +### Core Development + +```bash +# Start development server with hot reloading +docker compose run dev + +# Run comprehensive test suite +docker compose run test + +# Generate GraphQL TypeScript types +npm run generate + +# Build for development (install, codegen, tsc) +npm run build:dev +``` + +Only use Docker Compose for running tests, and only use `docker compose run test` +to run tests; don't try to run tests for individual files. + +## Architecture Overview + +Project Inter Server is a GraphQL-based backend for college transit tracking with real-time shuttle data, parking availability, and push notifications. + +- InterchangeSystem: Central orchestrator for shuttles, parking, and notifications + - Use `InterchangeSystem.build()` in production + - Use `InterchangeSystem.buildForTesting()` in tests + +- Repository Pattern (data access abstraction) + - Shuttle: `UnoptimizedInMemoryShuttleRepository` + - Parking: `InMemoryParkingRepository` + - Notifications: `RedisNotificationRepository` (prod) / `InMemoryNotificationRepository` (test) + +- Data Loaders (external API integration) + - `ApiBasedShuttleRepositoryLoader` – Passio GO! API + - `ChapmanApiBasedParkingRepositoryLoader` – Parking data + - `TimedApiBasedRepositoryLoader` – Periodic refresh wrapper + +- Notification System + - `ETANotificationScheduler` – Shuttle arrival notifications + - `AppleNotificationSender` – APNS integration + +## GraphQL + +- Schema definition: `schema.graphqls` +- Generated types: `src/generated/` +- Resolvers: `src/resolvers/` +- Resolver merge: `src/MergedResolvers.ts` + +## Directory Structure + +- `src/entities/` – Core business logic +- `src/repositories/` – Data access layer +- `src/loaders/` – External API integrations +- `src/notifications/` – Push notification system +- `src/resolvers/` – GraphQL resolvers and tests +- `testHelpers/` – Test utilities and mock data + +## Docker Services + +- `dev` – Development server with hot reload +- `test` – Unit/integration tests +- `redis` – Persistent Redis +- `redis-no-persistence` – Ephemeral Redis for tests + +## Testing Patterns + +- Prefer `buildForTesting()` to construct systems in tests. +- Mock external APIs using JSON snapshots under `testHelpers/jsonSnapshots`. +- Use in-memory repositories for speed where possible. +- When adding features that affect API output, add focused resolver tests in the corresponding `src/resolvers/__tests__` file. + - Separate unit tests from integration tests where practical to keep feedback fast and failures well-scoped. + +## Development Guidelines + +### General Guidelines + +- Use test-driven development where possible. Write tests before implementation and run them before and after changes. +- Use Docker Compose for tests. Run `docker compose run test` so you can see full output. + +### Git Workflow + +- Name pull requests after their branch name. + +### Code Style + +- Prefer arrow functions, especially within classes. +- Keep changes minimal and focused; avoid unrelated refactors. Mention incidental issues separately. +- Respect existing interfaces and types; use non-destructive edits. + +### Agent Tips + +- Write or update tests alongside changes; validate with `docker compose run test`. +- When touching GraphQL resolvers, co-locate new tests in `src/resolvers/__tests__`. + +## Multi-tenant Support + +Currently supports Chapman University (Passio System ID: `263`). Each university system uses isolated repositories and configuration. New systems should be added via `InterchangeSystem` configuration and appropriate loaders. \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index ff2a556..460e151 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,93 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code when working with code in this repository. - -## Development Commands - -### Core Development -```bash -# Start development server with hot reloading -docker compose run dev - -# Run comprehensive test suite -docker compose run test - -# Generate GraphQL TypeScript types -npm run generate - -# Build for development (install, codegen, tsc) -npm run build:dev -``` - -Only use Docker Compose for running tests, and only use `docker compose run test` -to run tests; don't try to run tests for individual files. - -## Architecture Overview - -Project Inter Server is a GraphQL-based backend for college transit tracking with real-time shuttle data, parking availability, and push notifications. - -- InterchangeSystem: Central orchestrator for shuttles, parking, and notifications - - Use `InterchangeSystem.build()` in production - - Use `InterchangeSystem.buildForTesting()` in tests - -- Repository Pattern (data access abstraction) - - Shuttle: `UnoptimizedInMemoryShuttleRepository` - - Parking: `InMemoryParkingRepository` - - Notifications: `RedisNotificationRepository` (prod) / `InMemoryNotificationRepository` (test) - -- Data Loaders (external API integration) - - `ApiBasedShuttleRepositoryLoader` – Passio GO! API - - `ChapmanApiBasedParkingRepositoryLoader` – Parking data - - `TimedApiBasedRepositoryLoader` – Periodic refresh wrapper - -- Notification System - - `ETANotificationScheduler` – Shuttle arrival notifications - - `AppleNotificationSender` – APNS integration - -## GraphQL -- Schema definition: `schema.graphqls` -- Generated types: `src/generated/` -- Resolvers: `src/resolvers/` -- Resolver merge: `src/MergedResolvers.ts` - -## Directory Structure -- `src/entities/` – Core business logic -- `src/repositories/` – Data access layer -- `src/loaders/` – External API integrations -- `src/notifications/` – Push notification system -- `src/resolvers/` – GraphQL resolvers and tests -- `testHelpers/` – Test utilities and mock data - -## Docker Services -- `dev` – Development server with hot reload -- `test` – Unit/integration tests -- `redis` – Persistent Redis -- `redis-no-persistence` – Ephemeral Redis for tests - -## Testing Patterns -- Prefer `buildForTesting()` to construct systems in tests. -- Mock external APIs using JSON snapshots under `testHelpers/jsonSnapshots`. -- Use in-memory repositories for speed where possible. -- When adding features that affect API output, add focused resolver tests in the corresponding `src/resolvers/__tests__` file. - - Separate unit tests from integration tests where practical to keep feedback fast and failures well-scoped. - -## Development Guidelines - -### General Guidelines -- Use test-driven development where possible. Write tests before implementation and run them before and after changes. -- Use Docker Compose for tests. Run `docker compose run test` so you can see full output. - -### Git Workflow -- Name pull requests after their branch name. - -### Code Style -- Prefer arrow functions, especially within classes. -- Keep changes minimal and focused; avoid unrelated refactors. Mention incidental issues separately. -- Respect existing interfaces and types; use non-destructive edits. - -### Agent Tips -- Write or update tests alongside changes; validate with `docker compose run test`. -- When touching GraphQL resolvers, co-locate new tests in `src/resolvers/__tests__`. - -## Multi-tenant Support -Currently supports Chapman University (Passio System ID: `263`). Each university system uses isolated repositories and configuration. New systems should be added via `InterchangeSystem` configuration and appropriate loaders. +See AGENTS.md \ No newline at end of file