project-inter-server/AGENTS.md

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

# 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

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