feat(backend): create cli to interact with db

CLAUDE.md

@@ -0,0 +1,124 @@
+# 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.