nimbusflow/CLAUDE.md

# CLAUDE.md

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

## Project Overview

NimbusFlow is a comprehensive scheduling system with a **monorepo structure** containing separate backend and frontend applications designed for church music ministry scheduling. The system handles round-robin member scheduling with sophisticated algorithms for fair distribution and availability management.

### Architecture Overview

- **Backend**: Python-based scheduling service with FastAPI REST API, SQLite database, and comprehensive CLI
- **Frontend**: .NET 8 Blazor Server application with Bootstrap UI for web-based management

## Backend Architecture

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

```
backend/
├── api/                # FastAPI REST API server
├── cli/                # Command-line interface
├── db/                 # Database connection layer
├── models/             # Data models and enums
├── repositories/       # Data access layer (Repository pattern)
├── services/           # Business logic layer
├── tests/              # Comprehensive test suite
├── utils/              # Utility functions
├── requirements.txt    # Python dependencies
└── schema.sql          # Database schema
```

### Key Components

#### API Layer (`api/`)
- **app.py**: FastAPI application with comprehensive REST endpoints
- **__main__.py**: Uvicorn server entry point with auto-reload
- Supports CORS for frontend communication on `localhost:5000/5001`
- Pydantic models for request/response validation with C# naming convention compatibility

#### CLI Layer (`cli/`)
- **main.py**: Command-line interface coordinator with subcommands
- **interactive.py**: Interactive mode for user-friendly operations  
- **commands/**: Modular command implementations (members, schedules, services)
- **base.py**: Base CLI class with common functionality

#### Database Layer (`db/`)
- **connection.py**: SQLite wrapper with context manager support
- **base_repository.py**: Abstract base repository with common CRUD operations
- Thread-safe connection handling for FastAPI

#### Repository Pattern (`repositories/`)
- **MemberRepository** (`member.py`): Member CRUD operations
- **ScheduleRepository** (`schedule.py`): Schedule management with status updates
- **ServiceRepository** (`service.py`): Service instance management
- **ClassificationRepository** (`classification.py`): Member role management
- **ServiceTypeRepository** (`service_type.py`): Time slot definitions
- **ServiceAvailabilityRepository** (`service_availability.py`): Member eligibility

#### Business Logic (`services/`)
- **SchedulingService** (`scheduling_service.py`): Core scheduling algorithms
  - Round-robin scheduling based on `LastAcceptedAt` timestamps
  - 5-day decline boost for recently declined members
  - Same-day exclusion rules
  - Multi-classification support
  - Status-aware scheduling (pending/accepted/declined)

#### Data Models (`models/`)
- **dataclasses.py**: Core data models with SQLite row conversion utilities
- **enums.py**: Enumerated types for system constants
- Models: Member, Service, Schedule, Classification, ServiceType, etc.

### Database Schema (`schema.sql`)

SQLite-based with comprehensive relational design:

**Core Tables:**
- `Members`: Member information with scheduling timestamps
- `Services`: Service instances with dates and types
- `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
- 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 (Members, Schedules, Services)
│   ├── App.razor       # Root application component
│   └── _Imports.razor  # Global imports
├── Models/             # C# models matching backend structure
├── Services/           # HTTP client services for API communication
├── Properties/         # Launch settings and configuration
├── wwwroot/           # Static files and assets
└── Program.cs         # Application startup and DI configuration
```

### Key Components

#### Services Layer
- **ApiService.cs**: HTTP client implementation with JSON serialization
- **IApiService.cs**: Service interface for dependency injection
- Configured for `http://localhost:8000/api/` backend communication
- Camel case JSON handling for API compatibility

#### Models (`Models/`)
- **Member.cs**: Complete data models matching backend structure
- Models: Member, Classification, Service, ServiceType, Schedule
- Navigation properties for related data
- Compatible with FastAPI Pydantic models

#### Razor Components (`Components/Pages/`)
- **Members.razor**: Member management interface
- **Schedules.razor**: Schedule management and workflow
- **Services.razor**: Service administration
- **Home.razor**: Dashboard and overview
- Bootstrap 5 styling with responsive design

#### Dependency Injection (`Program.cs`)
- HTTP client configuration for backend API
- Service registration with scoped lifetime
- HTTPS redirection and static file serving

## Development Commands

### Backend Development

**Environment Setup:**
```bash
cd backend
# Virtual environment is pre-configured in .venv/
source .venv/bin/activate
```

**Dependencies:**
```bash
# Install from requirements.txt
pip install -r requirements.txt
```

**API Server:**
```bash
cd backend
source .venv/bin/activate
python -m api
# Starts FastAPI server on http://localhost:8000
# API documentation at http://localhost:8000/docs
```

**CLI Usage:**
```bash
cd backend  
source .venv/bin/activate
python -m cli --help
python -m cli members list
python -m cli schedules schedule --help
```

**Demo/Development Data:**
```bash
cd backend
source .venv/bin/activate  
python main.py  # Runs demo data population
```

**Testing:**
```bash
cd backend
source .venv/bin/activate
pytest                    # Run all tests
pytest tests/repositories/ # Run repository tests
pytest --cov              # Run with coverage
```

### Frontend Development

**Setup:**
```bash
cd frontend
dotnet restore
```

**Development Server:**
```bash
cd frontend
dotnet watch    # Hot reload development
# Or: dotnet run
```

**Build & Deploy:**
```bash
cd frontend
dotnet build                    # Development build
dotnet build -c Release         # Production build
dotnet publish -c Release       # Publish for deployment
```

**Access:**
- Development: https://localhost:5001 (HTTPS) or http://localhost:5000 (HTTP)
- Expects backend API at http://localhost:8000/api/

## Core Business Logic

### Scheduling Algorithm

The **SchedulingService** implements sophisticated member scheduling:

1. **Round-robin fairness**: Based on `LastAcceptedAt` timestamps
2. **Decline boost**: 5-day priority for recently declined members  
3. **Same-day exclusion**: Members cannot serve multiple services per day
4. **Classification matching**: Multi-classification support for flexible roles
5. **Availability filtering**: Service type eligibility checking
6. **Status management**: Prevents double-booking across pending/accepted states

**Key Methods:**
- `schedule_next_member(classification_ids, service_id)`: Core scheduling with multi-role support
- `decline_service_for_user(member_id, service_id, reason)`: Decline handling with boost logic

### API Endpoints

**Member Management:**
- `GET /api/members` - List all members
- `GET /api/members/{id}` - Get member details
- `POST /api/members` - Create new member
- `PUT /api/members/{id}` - Update member
- `DELETE /api/members/{id}` - Delete member

**Scheduling Operations:**  
- `GET /api/schedules` - List all schedules
- `POST /api/schedules/schedule-next` - Schedule next available member
- `POST /api/schedules/{id}/accept` - Accept assignment
- `POST /api/schedules/{id}/decline` - Decline with reason
- `DELETE /api/schedules/{id}` - Remove schedule

**Service Management:**
- `GET /api/services` - List services  
- `POST /api/services` - Create new service
- `GET /api/service-types` - List service types

## Database Management

**Schema Location:** `backend/schema.sql`

**Database File:** `backend/db/sqlite/database.db` (auto-created)

**Key Features:**
- Automatic database creation from schema if missing
- Foreign key constraints enforced
- Comprehensive indexing for performance
- Audit logging for all schedule operations

## Testing

**Backend Testing with pytest:**
- Repository layer unit tests with in-memory SQLite
- Service layer business logic tests
- Fixtures for database setup and test data
- Comprehensive coverage of scheduling algorithms

**Test Structure:**
```
tests/
├── conftest.py              # Shared fixtures
├── repositories/            # Repository layer tests
└── services/               # Business logic tests
```

## Development Workflow

1. **Backend First**: Start with API development and testing
2. **Database Schema**: Modify `schema.sql` for data model changes  
3. **Repository Layer**: Update repositories for new database operations
4. **Service Layer**: Implement business logic in services
5. **API Layer**: Add FastAPI endpoints with Pydantic models
6. **Frontend Models**: Update C# models to match API
7. **Frontend Services**: Extend ApiService for new endpoints  
8. **Frontend UI**: Create/update Razor components
9. **Testing**: Add tests for new functionality
10. **Integration**: Test full stack communication

## Important Notes

- **Thread Safety**: FastAPI uses custom DatabaseConnection for thread safety
- **JSON Compatibility**: Backend uses PascalCase/camelCase aliasing for C# compatibility  
- **Error Handling**: Comprehensive HTTP status codes and error responses
- **CORS**: Configured for frontend origins on localhost:5000/5001
- **Virtual Environment**: Pre-configured Python environment in `backend/.venv/`
- **Auto-reload**: Both backend (Uvicorn) and frontend (dotnet watch) support hot reload