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


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