project-inter-server/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) 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

# Run integration tests with test data
docker compose run app-integration-tests

# Generate GraphQL TypeScript types
npm run generate

# Build for development
npm run build:dev

Testing

# Run all tests
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.

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
• app-integration-test - Integration with test data
• 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

Git Workflow

• Use the name of the branch for all pull requests