CLAUDE.md -> AGENTS.md
This commit is contained in:
103
AGENTS.md
Normal file
103
AGENTS.md
Normal file
@@ -0,0 +1,103 @@
|
|||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to all agents 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.
|
||||||
94
CLAUDE.md
94
CLAUDE.md
@@ -1,93 +1 @@
|
|||||||
# CLAUDE.md
|
See AGENTS.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.
|
|
||||||
Reference in New Issue
Block a user