mirror of
https://github.com/brendan-ch/project-inter-server.git
synced 2026-04-17 07:50:31 +00:00
104 lines
3.1 KiB
Markdown
104 lines
3.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) 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
|
|
|
|
# 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
|
|
```bash
|
|
# 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
|
|
|
|
### General Guidelines
|
|
- Use test-driven development. Always write tests before implementation, and run them before and after implementation.
|
|
|
|
### Git Workflow
|
|
- Use the name of the branch for all pull requests
|
|
|
|
### Code Style
|
|
- Prefer arrow functions, especially in classes
|