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:5059
• 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:

cd backend
# Virtual environment is pre-configured in .venv/
source .venv/bin/activate

Dependencies:

# Install from requirements.txt
pip install -r requirements.txt

API Server:

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:

cd backend  
source .venv/bin/activate
python -m cli --help
python -m cli members list
python -m cli schedules schedule --help

Demo/Development Data:

cd backend
source .venv/bin/activate  
python main.py  # Runs demo data population

Testing:

cd backend
source .venv/bin/activate
pytest                    # Run all tests
pytest tests/repositories/ # Run repository tests
pytest --cov              # Run with coverage

Frontend Development

Setup:

cd frontend
dotnet restore

Development Server:

cd frontend
dotnet watch    # Hot reload development
# Or: dotnet run

Build & Deploy:

cd frontend
dotnet build                    # Development build
dotnet build -c Release         # Production build
dotnet publish -c Release       # Publish for deployment

Access:

• Development: http://localhost:5059
• 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

Color Palette & Design System

The NimbusFlow brand uses a sophisticated color palette inspired by the logo's golden cloud and deep navy background, creating a professional yet warm aesthetic suitable for church ministry applications.

Primary Colors

:root {
  /* Primary Brand Colors */
  --nimbus-navy: #1a2332;        /* Deep navy background */
  --nimbus-navy-light: #2a3441;  /* Lighter navy variant */
  --nimbus-navy-dark: #0f1419;   /* Darker navy variant */
  
  /* Golden Accent Colors */
  --nimbus-gold: #ffd700;        /* Primary gold */
  --nimbus-gold-light: #ffed4e;  /* Light gold highlight */
  --nimbus-gold-dark: #e6c200;   /* Dark gold shadow */
  --nimbus-amber: #ffb347;       /* Warm amber accent */
  
  /* Neutral Colors */
  --nimbus-white: #ffffff;       /* Pure white */
  --nimbus-gray-100: #f8f9fa;    /* Light gray */
  --nimbus-gray-300: #dee2e6;    /* Medium light gray */
  --nimbus-gray-600: #6c757d;    /* Medium gray */
  --nimbus-gray-800: #343a40;    /* Dark gray */
}

Bootstrap Integration

/* Override Bootstrap variables */
:root {
  --bs-primary: var(--nimbus-navy);
  --bs-primary-rgb: 26, 35, 50;
  --bs-secondary: var(--nimbus-gold);
  --bs-secondary-rgb: 255, 215, 0;
  --bs-success: #28a745;
  --bs-warning: var(--nimbus-amber);
  --bs-info: #17a2b8;
  --bs-danger: #dc3545;
}

Usage Guidelines

Primary Navy (--nimbus-navy):

• Navigation bars and headers
• Card backgrounds in dark mode
• Button primary states
• Footer backgrounds

Golden Accent (--nimbus-gold):

• Call-to-action buttons
• Active states and highlights
• Icons and accent elements
• Success indicators

Amber (--nimbus-amber):

• Warning states
• Pending status indicators
• Hover effects on interactive elements

Accessibility Considerations

All color combinations meet WCAG 2.1 AA standards:

• Navy on White: 12.6:1 contrast ratio
• Gold on Navy: 4.8:1 contrast ratio
• White on Navy: 12.6:1 contrast ratio
• Dark Gray on Light Gray: 7.2:1 contrast ratio

Implementation Example

<!-- Primary navigation -->
<nav class="navbar navbar-expand-lg" style="background-color: var(--nimbus-navy);">
    <div class="navbar-brand text-white">
        <i class="bi bi-cloud" style="color: var(--nimbus-gold);"></i>
        NimbusFlow
    </div>
</nav>

<!-- Action button -->
<button class="btn" style="background-color: var(--nimbus-gold); color: var(--nimbus-navy);">
    Schedule Next Member
</button>

<!-- Status badges -->
<span class="badge" style="background-color: var(--nimbus-amber); color: var(--nimbus-navy);">
    Pending
</span>

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:5059
• Virtual Environment: Pre-configured Python environment in backend/.venv/
• Auto-reload: Both backend (Uvicorn) and frontend (dotnet watch) support hot reload
• Brand Colors: Use the defined color palette consistently across all UI components