From 87e5ab7b5b6179a06320ca4cc38f362134f183d7 Mon Sep 17 00:00:00 2001 From: derekc Date: Tue, 3 Mar 2026 08:44:08 -0800 Subject: [PATCH] Update README with break time and break activities features Co-Authored-By: Claude Sonnet 4.6 --- README.md | 42 ++++++++++++++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index a1fa774..04f36e8 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,12 @@ A self-hosted web app for managing homeschool schedules, tracking daily learning - **TV Dashboard** — Full-screen display for the living room TV. Shows the current subject, countdown timer, day progress, activity options, and the schedule 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" greeting 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. Managed inside the Admin page. +- **Break Time** — Each schedule block can optionally include a break at the end. Enable the checkbox and set a duration (in minutes) when building a block in Admin. Once the block's main timer is done, a **Break Time** section appears on the Dashboard with its own **Start / Pause / Resume / Reset** controls — the break does not start automatically. While break is active the TV left column switches to an amber break badge and countdown timer, and the center column shows the configurable **Break Activities** list instead of subject options. +- **Break Activities** — A global list of break-time activities (e.g. "Get a snack", "Go outside") managed in Admin → Break Activities, using the same add/edit/delete interface as Morning Routine. These items are shown on the TV during any active break. +- **Schedule Builder** — Create named schedule templates with time blocks assigned to subjects. Set optional school day start/end hours for a day-progress bar. Each block supports an optional custom duration override, label, and break time setting. Managed inside the Admin page. - **Daily Sessions** — Start a school day against a schedule template. Click any block in the list to select it as the current block. Use the **Start** button to begin timing, **Pause** to stop, **Resume** to continue from where you left off, and **Reset** to clear the elapsed time and restart the timer from zero. Elapsed time per block is remembered across switches, so returning to a block picks up where it left off. - **Block Timer Remaining** — Each block in the schedule list shows time remaining (allocated duration minus elapsed), counting down live on both the parent dashboard and the TV sidebar. Shows "< 1 min" when under a minute, and "Done!" when the full duration is elapsed. -- **Activity Log** — Automatically records every timer event (day started, block start/pause/resume/complete/skip/reset) 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. +- **Activity Log** — Automatically records every timer event (day started, block start/pause/resume/complete/skip/reset, break start/pause/resume/reset) 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. @@ -53,10 +55,11 @@ homeschool/ │ ├── models/ # SQLAlchemy ORM models │ │ ├── child.py │ │ ├── subject.py # Subject + SubjectOption -│ │ ├── schedule.py # ScheduleTemplate + ScheduleBlock +│ │ ├── schedule.py # ScheduleTemplate + ScheduleBlock (incl. break fields) │ │ ├── session.py # DailySession + TimerEvent │ │ ├── activity.py # ActivityLog (manual notes) │ │ ├── morning_routine.py# MorningRoutineItem +│ │ ├── break_activity.py # BreakActivityItem │ │ └── strike.py # StrikeEvent (strike history) │ ├── schemas/ # Pydantic request/response schemas │ ├── routers/ # API route handlers @@ -64,13 +67,14 @@ homeschool/ │ │ ├── children.py │ │ ├── subjects.py │ │ ├── schedules.py -│ │ ├── sessions.py # Timer actions, block selection, reset +│ │ ├── sessions.py # Timer actions + break timer events │ │ ├── logs.py # Timeline + strike events │ │ ├── morning_routine.py +│ │ ├── break_activity.py # Break activities CRUD │ │ ├── dashboard.py # Public snapshot endpoint (TV) │ │ └── users.py │ ├── utils/ -│ │ └── timer.py # Shared elapsed-time computation (reset-aware) +│ │ └── timer.py # Elapsed-time computation for block and break timers │ └── websocket/manager.py # WebSocket connection manager │ └── frontend/ @@ -143,8 +147,9 @@ Open **http://localhost:8054/login** and register. This creates your admin accou 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 greeting 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 +4. **Admin** → Add **Break Activities** items — these show on the TV center panel whenever a break is active. +5. **Admin** → Scroll to **Settings** and select your local timezone +6. **Admin** → Scroll to **Schedules** → Create a schedule template, set school day hours, add time blocks assigned to subjects. For any block that should include a break, check **Break** and enter the break duration in minutes. 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) @@ -158,12 +163,14 @@ Open **http://localhost:8054/login** and register. This creates your admin accou |-----|-------------| | `/dashboard` | Overview, start/stop sessions, select and time blocks, 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 | +| `/admin` | Manage children, subjects (with activity options), morning routine, break activities, schedule templates, and account settings | ### Dashboard Controls While a session is active, clicking a block in the schedule list **selects** it as the current block without starting the timer. The action buttons then provide explicit control: +**Main block timer:** + | Button | Condition | Action | |--------|-----------|--------| | **Start** | Block selected, never timed | Begin counting from zero | @@ -172,11 +179,20 @@ While a session is active, clicking a block in the schedule list **selects** it | **Reset** | Any current block | Clear elapsed to zero and restart timer immediately | | **End Day** | Session active | Mark the session complete | +**Break timer** (shown when the current block has Break Time enabled): + +| Button | Condition | Action | +|--------|-----------|--------| +| **Start Break** | Break not yet started | Begin break countdown from zero | +| **Pause** | Break timer running | Stop break countdown | +| **Resume** | Break timer paused | Continue break countdown | +| **Reset** | Break in progress | Clear break elapsed to zero and restart immediately | + ### TV Dashboard (no login) | URL | Description | |-----|-------------| -| `/tv/:childId` | Full-screen display — greeting + morning routine, current block timer, activity options, day progress, schedule sidebar | +| `/tv/:childId` | Full-screen display — greeting + morning routine, current block timer with subject activities, break timer with break activities, 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. @@ -208,12 +224,16 @@ The TV dashboard connects to `ws://host/ws/{child_id}` and receives JSON events: | Event | Triggered by | Key payload fields | |-------|-------------|---------| -| `session_update` | Session start | Full session snapshot including blocks, morning routine, and day times | +| `session_update` | Session start | Full session snapshot including blocks, morning routine, break activities, and day times | | `start` | Block timer started | `block_id`, `current_block_id`, `block_elapsed_seconds`, `prev_block_id`, `prev_block_elapsed_seconds` | | `pause` | Block timer paused | `block_id`, `current_block_id` | | `resume` | Block timer resumed | `block_id`, `current_block_id` | | `select` | Block selected (not started) | `block_id`, `current_block_id`, `block_elapsed_seconds`, `prev_block_id`, `prev_block_elapsed_seconds` | | `reset` | Block timer reset to zero | `block_id`, `current_block_id`, `block_elapsed_seconds` (always 0) | +| `break_start` | Break timer started | `block_id`, `current_block_id`, `break_elapsed_seconds` | +| `break_pause` | Break timer paused | `block_id`, `current_block_id` | +| `break_resume` | Break timer resumed | `block_id`, `current_block_id` | +| `break_reset` | Break timer reset to zero | `block_id`, `current_block_id`, `break_elapsed_seconds` (always 0) | | `complete` | Session ended | `is_active: false` | | `strikes_update` | Strike issued/cleared | `strikes` | @@ -221,6 +241,8 @@ The TV dashboard connects to `ws://host/ws/{child_id}` and receives JSON events: `prev_block_id` and `prev_block_elapsed_seconds` on `start` and `select` events carry the saved elapsed for the block being left, so the TV sidebar immediately shows the correct remaining time for that block. +Break timer events (`break_*`) are stored as `TimerEvent` records alongside regular timer events but are computed and broadcast independently — they do not affect block selection, implicit pauses, or elapsed time for the main block timer. + --- ## Environment Variables Reference