homeschool/README.md

# Homeschool Dashboard

A self-hosted web app for managing homeschool schedules, tracking daily learning sessions, and logging activities. Features a full-screen TV dashboard with live timers and real-time updates via WebSockets.

---

## Features

- **TV Dashboard** — Full-screen display for the living room TV. Shows the current subject, countdown timer, day progress, activity options, and the upcoming block list. Updates live without page refresh via WebSocket.
- **Morning Routine** — Define a list of morning routine items in Admin. They appear in the TV dashboard Activities panel during the "Good Morning" countdown before the first block starts, then switch to subject-specific activities once a block begins.
- **Schedule Builder** — Create named schedule templates with time blocks assigned to subjects. Set optional school day start/end hours for a day-progress bar. Assign templates per-child or share across all children. Managed inside the Admin page.
- **Daily Sessions** — Start a school day against a schedule template. Track which blocks are active, paused, or complete. Click any block in the list to switch to it instantly — the current block is auto-paused and the new one starts in a single click. Elapsed time per block is remembered, so returning to a block resumes the timer from where it left off.
- **Block Timer Remaining** — Each block in the schedule list shows how much time is left on that block's timer (allocated duration minus elapsed time already spent), counting down live on both the parent dashboard and the TV sidebar.
- **Activity Log** — Automatically records every timer event (day started, block start/pause/resume/complete/skip) and every strike change as a timestamped timeline. Includes which schedule template was used. Supports manual notes with free text. Browse and filter history by child and date.
- **Behavior Tracking (Strikes)** — Issue up to 3 strikes per child from the Dashboard. Strike additions and removals are logged in the activity log with a timestamp. Strike count is shown on the TV dashboard and resets automatically when a new school day begins.
- **Timezone Support** — Set your local timezone in Admin → Settings. All activity log timestamps display in your timezone, including the TV dashboard clock.
- **Multi-Child Support** — Manage multiple students under one parent account, each with their own color, schedule, and history.
- **JWT Authentication** — Secure parent login with access tokens and httpOnly refresh cookies. TV dashboard is public (no login required).

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Frontend | Vue 3 + Vite + Pinia + Vue Router |
| Frontend server | nginx (Docker) |
| Backend API | FastAPI (Python 3.12) |
| Real-time | WebSockets via FastAPI |
| Database | MySQL 8 |
| ORM | SQLAlchemy 2.0 (async) |
| Auth | JWT — python-jose + passlib/bcrypt |
| Orchestration | Docker Compose |

---

## Project Structure

```
homeschool/
├── docker-compose.yml            # Stack definition (3 services: db, backend, frontend)
├── .env.example                  # Environment variable template
│
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app/
│       ├── main.py               # FastAPI app entry point + table auto-creation
│       ├── config.py             # Settings (reads from .env)
│       ├── database.py           # Async SQLAlchemy engine
│       ├── dependencies.py       # Auth dependencies (get_current_user)
│       ├── auth/jwt.py           # Token creation, password hashing
│       ├── models/               # SQLAlchemy ORM models
│       │   ├── child.py
│       │   ├── subject.py        # Subject + SubjectOption
│       │   ├── schedule.py       # ScheduleTemplate + ScheduleBlock
│       │   ├── session.py        # DailySession + TimerEvent
│       │   ├── activity.py       # ActivityLog (manual notes)
│       │   ├── morning_routine.py# MorningRoutineItem
│       │   └── strike.py         # StrikeEvent (strike history)
│       ├── schemas/              # Pydantic request/response schemas
│       ├── routers/              # API route handlers
│       │   ├── auth.py
│       │   ├── children.py
│       │   ├── subjects.py
│       │   ├── schedules.py
│       │   ├── sessions.py       # Timer actions + block switching
│       │   ├── logs.py           # Timeline + strike events
│       │   ├── morning_routine.py
│       │   ├── dashboard.py      # Public snapshot endpoint (TV)
│       │   └── users.py
│       └── websocket/manager.py  # WebSocket connection manager
│
└── frontend/
    ├── Dockerfile                # Multi-stage: Node build → nginx serve
    ├── nginx.conf                # Proxy /api/ and /ws/ to backend
    └── src/
        ├── composables/
        │   ├── useApi.js         # Axios with auto token-refresh
        │   └── useWebSocket.js   # Auto-reconnecting WebSocket
        ├── stores/               # Pinia: auth, children, schedule
        ├── views/                # LoginView, TVView, DashboardView, LogView, AdminView
        └── components/           # TimerDisplay, ScheduleBlock, NavBar, etc.
```

---

## Getting Started

### Prerequisites

- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed
- Port `8054` available on the host (or change it in `docker-compose.yml`)

### 1. Clone the repo

```bash
git clone https://git.chns.tech/CooperandGoodman/homeschool.git
cd homeschool
```

### 2. Create your `.env` file

```bash
cp .env.example .env
```

Open `.env` and fill in the values:

```env
MYSQL_ROOT_PASSWORD=your_secure_root_password
MYSQL_DATABASE=homeschool
MYSQL_USER=homeschool
MYSQL_PASSWORD=your_secure_db_password

# Generate with: openssl rand -hex 32
SECRET_KEY=your_generated_secret_key

ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=30

# Your host IP or domain (no trailing slash)
CORS_ORIGINS=http://localhost:8054
```

### 3. Build and start

```bash
docker compose up --build
```

The first build takes a few minutes (npm install + pip install). On subsequent starts it's fast.

### 4. Register your parent account

Open **http://localhost:8054/login** and register. This creates your admin account.

### 5. Set up your data (in order)

1. **Admin** (`/admin`) → Add each child, pick a color
2. **Admin** → Add subjects (Math, Reading, Science, etc.) with emoji icons and colors. Add activity options to each subject — they appear on the TV dashboard during that block.
3. **Admin** → Add **Morning Routine** items — these show on the TV during the countdown before the first block starts.
4. **Admin** → Scroll to **Settings** and select your local timezone
5. **Admin** → Scroll to **Schedules** → Create a schedule template, set school day hours, add time blocks assigned to subjects
6. **Dashboard** (`/dashboard`) → Click "Start Day", choose a template
7. **TV** → Open `http://your-lan-ip:8054/tv/1` on the living room TV (replace `1` with the child's ID)

---

## Usage

### Parent Views (require login)

| URL | Description |
|-----|-------------|
| `/dashboard` | Overview, start/stop sessions, switch blocks, timer controls, issue behavior strikes |
| `/logs` | Browse timer and strike event history and manual notes; filter by child and date |
| `/admin` | Manage children, subjects (with activity options), morning routine, schedule templates, and account settings |

### TV Dashboard (no login)

| URL | Description |
|-----|-------------|
| `/tv/:childId` | Full-screen display — greeting + morning routine, current block timer, activity options, day progress, schedule sidebar |

Point a browser on the living room TV at `http://your-lan-ip:8054/tv/1`. The page connects via WebSocket and updates automatically when a parent starts/stops/advances the timer from the Dashboard.

### API Documentation

FastAPI auto-generates interactive API docs:

- **Swagger UI** — `http://localhost:8054/api/docs`
- **ReDoc** — `http://localhost:8054/api/redoc`

---

## Schema Migrations

The app automatically creates all database tables on startup via SQLAlchemy's `create_all`. Additive column changes are applied with idempotent `ALTER TABLE` statements in the startup lifespan, so upgrading to a new version is safe — just rebuild and restart:

```bash
docker compose build
docker compose up -d
```

No separate migration tool or manual steps are required.

---

## WebSocket Events

The TV dashboard connects to `ws://host/ws/{child_id}` and receives JSON events:

| Event | Triggered by | Key payload fields |
|-------|-------------|---------|
| `session_update` | Session start/end | Full session snapshot |
| `start` | Block started | `block_id`, `current_block_id`, `block_elapsed_seconds` |
| `pause` | Block paused | `block_id`, `current_block_id` |
| `resume` | Block resumed | `block_id`, `current_block_id` |
| `complete` | Block completed | `block_id` |
| `skip` | Block skipped | `block_id` |
| `strikes_update` | Strike issued/cleared | `strikes` |

`block_elapsed_seconds` on the `start` event carries the authoritative elapsed time for that block (including all previous intervals), so every client — including the TV — can restore the correct timer offset without a local cache.

---

## Environment Variables Reference

| Variable | Required | Description |
|----------|----------|-------------|
| `MYSQL_ROOT_PASSWORD` | Yes | MySQL root password |
| `MYSQL_DATABASE` | Yes | Database name (default: `homeschool`) |
| `MYSQL_USER` | Yes | App database user |
| `MYSQL_PASSWORD` | Yes | App database password |
| `SECRET_KEY` | Yes | JWT signing key — generate with `openssl rand -hex 32` |
| `ALGORITHM` | No | JWT algorithm (default: `HS256`) |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | No | Access token lifetime (default: `30`) |
| `REFRESH_TOKEN_EXPIRE_DAYS` | No | Refresh token lifetime (default: `30`) |
| `CORS_ORIGINS` | No | Comma-separated allowed origins (default: `http://localhost:8054`) |

---

## Stopping and Restarting

```bash
# Stop containers (data preserved in Docker volume)
docker compose down

# Stop and wipe the database volume (full reset)
docker compose down -v

# Restart without rebuilding
docker compose up
```