diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..643118a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,97 @@
+# 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
+
+### Git Workflow
+- Use the name of the branch for all pull requests
\ No newline at end of file