diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cfeabf8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,102 @@ +# AGENTS.md + +This file provides guidance to coding agents (e.g., Codex CLI, Claude Code, and other AI coding assistants) 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 +``` + +### Testing +```bash +# Run all tests via npm +npm test + +# Run specific test file +npm test -- --testPathPattern= + +# Run tests with coverage +npm test -- --coverage +``` + +## 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. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 4b22fa4..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,101 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/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 -npm run build:dev -``` - -### Testing -```bash -# Run all tests -npm test - -# Run specific test file -npm test -- --testPathPattern= - -# Run tests with coverage -npm test -- --coverage -``` - -## Architecture Overview - -**Project Inter Server** is a GraphQL-based backend for college transit tracking with real-time shuttle data, parking availability, and push notifications. - -### Core Components - -1. **InterchangeSystem** - Central orchestrator managing shuttles, parking, and notifications - - Use `InterchangeSystem.build()` for production - - Use `InterchangeSystem.buildForTesting()` for tests - -2. **Repository Pattern** - Data access abstraction - - Shuttle: `UnoptimizedInMemoryShuttleRepository` - - Parking: `InMemoryParkingRepository` - - Notifications: `RedisNotificationRepository` (prod) / `InMemoryNotificationRepository` (test) - -3. **Data Loaders** - External API integration - - `ApiBasedShuttleRepositoryLoader` - Passio GO! API integration - - `ChapmanApiBasedParkingRepositoryLoader` - University parking data - - `TimedApiBasedRepositoryLoader` - Periodic data refresh - -4. **Notification System** - - `ETANotificationScheduler` - Manages shuttle arrival notifications - - `AppleNotificationSender` - APNS integration - - Default threshold: 180 seconds - -### GraphQL Schema -- Schema definition: `schema.graphqls` -- Generated types: `src/generated/` -- Resolvers: `src/resolvers/` -- Combined in: `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 -- `test/` - Comprehensive test suite with mock data - -### Multi-tenant Support -Currently supports Chapman University (Passio System ID: "263"). Each university system has: -- System-specific configurations -- Isolated data repositories -- Custom API integrations - -### Docker Services -- `dev` - Development with hot reload -- `test` - Unit/integration testing -- `redis` - Persistent Redis -- `redis-no-persistence` - Ephemeral Redis for tests - -### Testing Patterns -- Use `buildForTesting()` for InterchangeSystem in tests -- Mock external APIs with JSON snapshots in test data -- Separate unit tests from integration tests -- Use in-memory repositories for faster testing - -## Development Guidelines - -### General Guidelines -- Use test-driven development. Always write tests before implementation, and run them before and after implementation. -- Use Docker Compose for tests. Make sure you run it in a way where you can actually see the test result. - -### Git Workflow -- Use the name of the branch for all pull requests - -### Code Style -- Prefer arrow functions, especially in classes \ No newline at end of file