nimbusflow/CLAUDE.md

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:

cd backend
# Activate virtual environment (already exists)
source venv/bin/activate

Testing:

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:

cd backend
# Run the demo script
python main.py

Frontend

Setup:

cd frontend
# Restore NuGet packages
dotnet restore

Development:

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.