# 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**: .NET Blazor Server application with Bootstrap UI

### 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

.NET 8 Blazor Server application with the following structure:

```
frontend/
├── Components/
│   ├── Layout/         # Layout components (NavMenu, MainLayout)
│   └── Pages/          # Razor pages (Dashboard, Members, Schedules, Services)
├── Models/             # C# models matching backend data structure
├── Services/           # HTTP client services for API communication
└── wwwroot/           # Static files and assets
```

**Key Components:**

- **ApiService** (`Services/ApiService.cs`): HTTP client wrapper for Python backend API communication
- **Models** (`Models/Member.cs`): C# data models (Member, Schedule, Service, Classification, etc.)
- **Razor Components**: Interactive pages for member management, scheduling, and service administration
- **Bootstrap UI**: Responsive design with Bootstrap 5 styling

The frontend communicates with the Python backend via HTTP API calls, expecting JSON responses that match the C# model structure.

## 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
# Restore NuGet packages
dotnet restore
```

**Development:**
```bash
cd frontend
# Start development server (with hot reload)
dotnet watch
# Or run without watch
dotnet run

# Build for production
dotnet build
# Publish for deployment
dotnet publish -c Release
```

**Access:**
- Development: https://localhost:5001 (HTTPS) or http://localhost:5000 (HTTP)
- The application expects the Python backend API to be available at http://localhost:8000/api/

## 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.