# 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.