146 lines
4.7 KiB
Markdown
146 lines
4.7 KiB
Markdown
# 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. |