RTSport Backend

FastAPI-based REST API for athletic training case management in scholastic sports.

Architecture

• Framework: FastAPI 0.111.0
• Database: PostgreSQL with SQLAlchemy ORM
• Schemas: Pydantic v2
• Auth: JWT-based (FERPA-compliant role system)

Quick Start

Prerequisites

• Python 3.11+
• PostgreSQL 14+

Installation

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your database credentials

Database Setup

# Create database
createdb rtsport

# Initialize tables
python -c "from app.database import init_db; init_db()"

Running the Server

# Development (with auto-reload)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Production
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Project Structure

backend/
├── app/
│   ├── __init__.py
│   ├── main.py           # FastAPI app factory
│   ├── config.py         # Settings management
│   ├── database.py       # SQLAlchemy engine/session
│   ├── schemas.py        # Pydantic v2 schemas (5 models)
│   ├── models.py         # SQLAlchemy ORM models
│   └── api/
│       ├── __init__.py
│       ├── roster.py     # GET /api/v1/roster
│       ├── cases.py      # GET /api/v1/cases/*
│       └── events.py     # POST /api/v1/events/sideline-entry
├── requirements.txt
└── README.md

API Endpoints

Read Operations

Write Operations

Data Models

1. School (Tenant)

• Multi-tenant boundary - every model has school_id
• Config JSON for branding and sport name mappings

2. Athlete

• Central roster node
• current_status: cached property (cleared|restricted|out)
• Updated via DB trigger on event creation

3. Case

• Single injury lifecycle
• severity (clinical, static) ≠ attention_level (operational, daily)
• Resolved via clearance_granted event (reopenable within 30 days)

4. Milestone

• Forward-looking targets (Phase Bar UI)
• Separate from Events (backward-looking records)

5. Event

• Every sideline entry, note, or clearance
• visibility defaults to ["at"] - must explicitly expand
• clinical_notes stripped server-side for non-AT roles

FERPA Compliance

Role-based access matrix:

Environment Variables

# Required
DATABASE_URL=postgresql://user:pass@localhost:5432/rtsport
SECRET_KEY=your-secret-key-here

# Optional
DEBUG=true
ACCESS_TOKEN_EXPIRE_MINUTES=10080  # 7 days
CORS_ORIGINS=["http://localhost:3000"]

Development Notes

Auto-Case Creation (Sideline Entry)

The POST /api/v1/events/sideline-entry endpoint:
1. Checks for existing active case for athlete + body_part
2. Creates new Case if none exists
3. Creates initial Event
4. Updates athlete.current_status via DB trigger

Status Synchronization

SQLAlchemy event listeners in models.py handle:
- restriction_added event → athlete.status = "restricted"
- clearance_granted event → athlete.status = "cleared" + case.resolved

Database Indexes

All tables indexed on:
- school_id (tenant isolation)
- Foreign keys (query performance)
- Array fields using GIN (JSONB/ARRAY queries)

Testing

# Run tests (when implemented)
pytest

# With coverage
pytest --cov=app --cov-report=html

Contract Alignment

Source of truth: ../docs/contract.md

• All 5 Pydantic schemas validate against contract §1
• All 4 GET + 1 POST endpoints match contract §2
• FERPA matrix implemented per contract §3
• Multi-tenant by school_id per contract §4