Move CLAUDE.md to AGENTS.md

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=<test-file-name>
+
+# 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.