mirror of
https://github.com/brendan-ch/project-inter-server.git
synced 2026-04-16 23:40:32 +00:00
Move CLAUDE.md to AGENTS.md
This commit is contained in:
102
AGENTS.md
Normal file
102
AGENTS.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# AGENTS.md
|
||||
|
||||
This file provides guidance to coding agents (e.g., Codex CLI, Claude Code, and other AI coding assistants) 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
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run all tests via npm
|
||||
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.
|
||||
|
||||
- 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.
|
||||
101
CLAUDE.md
101
CLAUDE.md
@@ -1,101 +0,0 @@
|
||||
# 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
|
||||
|
||||
|
||||
# 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
|
||||
- `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
|
||||
Reference in New Issue
Block a user