mirror of
https://github.com/brendan-ch/project-inter-server.git
synced 2026-04-16 23:40:32 +00:00
94 lines
3.5 KiB
Markdown
94 lines
3.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude 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
|
||
|
||
# Generate GraphQL TypeScript types
|
||
npm run generate
|
||
|
||
# Build for development (install, codegen, tsc)
|
||
npm run build:dev
|
||
```
|
||
|
||
Only use Docker Compose for running tests, and only use `docker compose run test`
|
||
to run tests; don't try to run tests for individual files.
|
||
|
||
## 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.
|