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

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
npm install

Development:

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.