# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Architecture

NimbusFlow is a scheduling system with a **monorepo structure** containing separate backend and frontend applications:

- **Backend**: Python-based scheduling service using SQLite with a repository pattern
- **Frontend**: React + TypeScript + Vite application

### Backend Architecture

The backend follows a **layered architecture** with clear separation of concerns:

```
backend/
├── db/              # Database connection layer
├── models/          # Data models and enums
├── repositories/    # Data access layer
├── services/        # Business logic layer
└── tests/          # Test suite
```

**Key Components:**

- **DatabaseConnection** (`db/connection.py`): SQLite wrapper with context manager support
- **Repository Pattern**: Each domain entity has its own repository (Member, Service, Classification, etc.)
- **SchedulingService** (`services/scheduling_service.py`): Core business logic for round-robin scheduling with boost/cooldown algorithms
- **Data Models** (`models/dataclasses.py`): Dataclasses with SQLite row conversion utilities

**Database Schema** (`schema.sql`): SQLite-based with tables for Members, Services, Classifications, Schedules, and audit logging. Uses foreign key constraints and indexes for performance.

### Frontend Architecture

React application using:
- TypeScript for type safety
- Vite for fast development and building
- ESLint for code linting

## Development Commands

### Backend

**Setup:**
```bash
cd backend
# Activate virtual environment (already exists)
source venv/bin/activate
```

**Testing:**
```bash
cd backend
# Run tests using pytest from virtual environment
venv/bin/pytest
# Run specific test file
venv/bin/pytest tests/repositories/test_member.py
# Run with coverage
venv/bin/pytest --cov
```

**Run Application:**
```bash
cd backend
# Run the demo script
python main.py
```

### Frontend

**Setup:**
```bash
cd frontend
npm install
```

**Development:**
```bash
cd frontend
# Start development server
npm run dev
# Build for production
npm run build
# Run linting
npm run lint
# Preview production build
npm run preview
```

## Core Business Logic

The **SchedulingService** implements a sophisticated member scheduling algorithm:

1. **Round-robin scheduling** based on `Members.LastAcceptedAt` timestamps
2. **5-day decline boost** - recently declined members get priority
3. **Same-day exclusion** - members can't be scheduled for multiple services on the same day
4. **Service availability** - members must be eligible for the specific service type
5. **Status constraints** - prevents double-booking (pending/accepted/declined statuses)

**Key Methods:**
- `schedule_next_member()` - Core scheduling logic with multi-classification support
- `decline_service_for_user()` - Handle member declining assignments

## Database

The system uses **SQLite** with the following key tables:
- `Members` - Core member data with scheduling timestamps
- `Services` - Service instances on specific dates
- `Schedules` - Member-service assignments with status tracking
- `Classifications` - Member roles (Soprano, Alto, Tenor, Baritone)
- `ServiceTypes` - Time slots (9AM, 11AM, 6PM)
- `ServiceAvailability` - Member eligibility for service types

**Audit Tables**: `AcceptedLog`, `DeclineLog`, `ScheduledLog` for comprehensive tracking.

## Testing

Backend uses **pytest** with fixtures for database setup. Tests cover:
- Repository layer functionality
- Business logic in services
- Database schema constraints

All tests use in-memory SQLite databases created fresh for each test.