124 lines
3.6 KiB
Markdown
124 lines
3.6 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**: 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:**
|
|
```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
|
|
npm install
|
|
```
|
|
|
|
**Development:**
|
|
```bash
|
|
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. |