Deploy Tech Presenter Coach

.dockerignore

@@ -0,0 +1,12 @@
+.git
+.github
+node_modules
+apps/web/.next
+.venv
+data/*
+!data/.gitkeep
+*.db
+__pycache__
+.pytest_cache
+Speech_Machine_Banner.png
+Screenshot_Speech_Machine.png

.env.example

@@ -0,0 +1,38 @@
+# Web
+NEXT_PUBLIC_API_URL=http://localhost:8000
+NEXT_PUBLIC_LOCAL_ONLY_MODE=true
+
+# API
+DATABASE_URL=postgresql+psycopg2://video:video@db:5432/video
+JWT_SECRET=change-me
+JWT_ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=15
+REFRESH_TOKEN_EXPIRE_DAYS=7
+ENVIRONMENT=development
+CORS_ORIGINS=http://localhost:3000
+LOCAL_ONLY_MODE=true
+MAX_UPLOAD_MB=500
+REDIS_HOST=redis
+REDIS_PORT=6379
+STORAGE_BACKEND=local
+STORAGE_DIR=/data/storage
+S3_ENDPOINT=
+S3_ACCESS_KEY=
+S3_SECRET_KEY=
+S3_BUCKET=
+S3_REGION=
+TRANSCRIPTION_BACKEND=server
+# Server transcription model: faster-whisper models plus nvidia/parakeet-tdt-0.6b-v3
+WHISPER_MODEL=small
+WHISPER_DEVICE=cpu
+# Desktop-only MLX Audio default model
+MLX_AUDIO_MODEL=mlx-community/parakeet-tdt-0.6b-v3
+OLLAMA_BASE_URL=http://127.0.0.1:11434
+LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1
+LLAMA_CPP_BASE_URL=http://127.0.0.1:8080
+LOCAL_ENGINE_TIMEOUT_SECONDS=0.75
+COACHING_ENABLED=true
+COACHING_PROVIDER=ollama
+COACHING_MODEL=llama3.2:3b
+COACHING_TIMEOUT_SECONDS=90
+COACHING_MAX_TRANSCRIPT_CHARS=8000

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug Report
+about: Report something that is not working
+labels: bug
+---
+
+## Description
+
+## Steps to reproduce
+1.
+2.
+3.
+
+## Expected behavior
+
+## Actual behavior
+
+## Environment
+- OS:
+- Browser:
+- Docker version:
+- Commit:
+
+## Logs
+
+```text
+Paste relevant logs here and redact secrets.
+```

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature Request
+about: Suggest an improvement
+labels: enhancement
+---
+
+## Problem
+
+## Proposed solution
+
+## Alternatives considered

.github/workflows/ci.yml

@@ -0,0 +1,102 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODE_VERSION: "20"
+  PYTHON_VERSION: "3.11"
+
+jobs:
+  web:
+    name: Web
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - run: npm ci
+      - run: npm --workspace apps/web run lint
+      - run: npm --workspace apps/web exec tsc -- --noEmit
+      - run: npm --workspace apps/web test -- --run
+      - run: npm --workspace apps/web run build
+        env:
+          NEXT_TELEMETRY_DISABLED: 1
+
+  shared:
+    name: Shared
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - run: npm ci
+      - run: npm --workspace packages/shared exec tsc -- --noEmit
+
+  api:
+    name: API
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: video
+          POSTGRES_PASSWORD: video
+          POSTGRES_DB: video
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U video -d video"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 5
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 5
+    defaults:
+      run:
+        working-directory: apps/api
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+          cache-dependency-path: apps/api/requirements-dev.txt
+      - run: python -m pip install --upgrade pip
+      - run: pip install -r requirements-dev.txt
+      - run: ruff check .
+      - run: mypy src/app --ignore-missing-imports --no-error-summary
+      - run: PYTHONPATH=src pytest -q --cov=app --cov-report=term-missing
+        env:
+          DATABASE_URL: sqlite:///./ci_test.db
+          JWT_SECRET: ci-test-secret
+          ENVIRONMENT: test
+          CORS_ORIGINS: http://localhost:3000
+
+  docker:
+    name: Docker Build
+    runs-on: ubuntu-latest
+    needs: [web, shared, api]
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker compose build

.gitignore

@@ -0,0 +1,42 @@
+# Environment
+.env
+.env.*
+!.env.example
+
+# Dependencies
+node_modules/
+apps/api/.venv/
+.venv/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+test_*.db
+local.db
+
+# Frontend
+.next/
+apps/web/public/pdf.worker.min.mjs
+out/
+dist/
+*.tsbuildinfo
+coverage/
+playwright-report/
+test-results/
+
+# Runtime data
+uploads/
+storage/
+models/
+*.zip
+
+# OS / IDE
+.DS_Store
+.idea/
+.vscode/

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing to Speech-Machine
+
+## Development setup
+
+1. Copy `.env.example` to `.env`.
+2. Set `JWT_SECRET` to a generated secret.
+3. Run `docker compose up --build`.
+4. Open `http://localhost:3000` and complete first-run setup.
+
+## Tests
+
+```bash
+npm --workspace apps/web test -- --run
+npm --workspace packages/shared exec tsc -- --noEmit
+cd apps/api && PYTHONPATH=src pytest -q
+```
+
+## Code style
+
+- Frontend: `npm --workspace apps/web run lint`.
+- Backend: `cd apps/api && ruff check .`.
+- Keep API route prefixes stable unless a migration plan is included.
+
+## Pull requests
+
+Use a branch from `main`, include tests for behavior changes, and verify Docker still builds.

Dockerfile

@@ -0,0 +1,40 @@
+FROM node:20-bookworm-slim
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONUNBUFFERED=1 \
+    HOME=/app/data/home \
+    INTERNAL_API_URL="http://127.0.0.1:8000" \
+    ALLOW_FRAME_EMBEDDING="true" \
+    PORT=7860
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 \
+    python3-pip \
+    ffmpeg \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python backend + cloud DB/S3 dependencies
+RUN pip3 install --no-cache-dir --break-system-packages \
+    fastapi "uvicorn[standard]" sqlalchemy psycopg2-binary pydantic pydantic-settings \
+    python-multipart "python-jose[cryptography]" "passlib[bcrypt]" "bcrypt<4.1" \
+    httpx email-validator faster-whisper arq reportlab boto3
+
+# Install Node.js workspace dependencies
+COPY package.json package-lock.json tsconfig.base.json ./
+COPY packages/shared/package.json ./packages/shared/package.json
+COPY apps/web/package.json ./apps/web/package.json
+RUN npm ci --no-audit --no-fund
+
+# Copy application source and build Next.js production bundle
+COPY . .
+RUN chmod +x /app/infra/scripts/start_cloud.sh /app/infra/scripts/run_presenter_coach.sh \
+    && mkdir -p /app/data/storage /app/data/home \
+    && npm --workspace apps/web run build \
+    && chmod -R 777 /app/data /app/apps/web/.next
+
+EXPOSE 7860
+
+CMD ["/app/infra/scripts/start_cloud.sh"]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Makefile

@@ -0,0 +1,85 @@
+SHELL := /bin/bash
+
+COMPOSE ?= docker compose
+API_VENV ?= $(HOME)/venvs/mlx
+API_PYTHON ?= $(API_VENV)/bin/python
+API_PYTEST ?= PYTHONPATH=src $(API_PYTHON) -m pytest -q
+API_RUFF ?= $(API_VENV)/bin/ruff
+API_MYPY ?= $(API_VENV)/bin/mypy
+ADMIN_EMAIL ?= admin@example.com
+ADMIN_PASSWORD ?= change-me-strong
+
+.PHONY: help install install-web install-api dev up local-up local-build down logs reset-local smoke local-smoke test test-web test-api lint lint-web lint-api typecheck typecheck-web typecheck-shared typecheck-api check compose-config format
+
+help:
+	@awk 'BEGIN {FS = ":.*##"; printf "Speech-Machine local targets:\n"} /^[a-zA-Z0-9_-]+:.*##/ {printf "  %-18s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: install-web install-api ## Install local web and API dependencies.
+
+install-web: ## Install root npm workspaces.
+	npm ci
+
+install-api: ## Install API dependencies into API_VENV, defaulting to ~/venvs/mlx.
+	cd apps/api && $(API_PYTHON) -m pip install -r requirements-dev.txt
+
+dev: local-up ## Start the local Docker stack.
+
+up: local-up ## Start the local Docker stack.
+
+local-up: .env ## Start the local Docker stack with rebuilds when needed.
+	$(COMPOSE) up --build
+
+local-build: ## Build local Docker images.
+	$(COMPOSE) build api worker web
+
+down: ## Stop local Docker services.
+	$(COMPOSE) down
+
+logs: ## Follow local Docker logs.
+	$(COMPOSE) logs -f api worker web
+
+reset-local: ## Stop services and delete local Docker volumes.
+	$(COMPOSE) down -v
+
+smoke: local-smoke ## Run local endpoint smoke checks.
+
+local-smoke: ## Check local API, setup, login, and web endpoints.
+	ADMIN_EMAIL="$(ADMIN_EMAIL)" ADMIN_PASSWORD="$(ADMIN_PASSWORD)" ./scripts/local-smoke.sh
+
+test: test-web test-api ## Run frontend and backend tests.
+
+test-web: ## Run frontend unit tests once.
+	npm --workspace apps/web test -- --run
+
+test-api: ## Run API tests through API_VENV.
+	cd apps/api && $(API_PYTEST)
+
+lint: lint-web lint-api ## Run web and API lint checks.
+
+lint-web: ## Run Next.js lint.
+	npm --workspace apps/web run lint
+
+lint-api: ## Run Ruff against the API.
+	cd apps/api && $(API_RUFF) check .
+
+typecheck: typecheck-shared typecheck-web typecheck-api ## Run TypeScript and Python type checks.
+
+typecheck-web: ## Run web TypeScript check.
+	npm --workspace apps/web exec tsc -- --noEmit
+
+typecheck-shared: ## Run shared package TypeScript check.
+	npm --workspace packages/shared exec tsc -- --noEmit
+
+typecheck-api: ## Run API mypy check.
+	cd apps/api && $(API_MYPY) src/app --ignore-missing-imports --no-error-summary
+
+check: test-web typecheck-shared lint-web typecheck-web test-api lint-api typecheck-api compose-config ## Run the local pre-commit check suite.
+
+compose-config: ## Validate Docker Compose config.
+	$(COMPOSE) config >/dev/null
+
+format: ## Format frontend files.
+	npm --workspace apps/web run format
+
+.env:
+	cp .env.example .env

NOTICE

@@ -0,0 +1,29 @@
+Speech-Machine — Personalized Tech Camera-Presenting Coach Edition
+Copyright 2026 Susant Achary (Original Speech-Machine Author)
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Summary of Modifications (Apache License 2.0, Section 4(b)):
+- Preserved Speech-Machine's core monorepo architecture (Next.js 14 frontend,
+  FastAPI + SQLAlchemy backend, @video/shared scoring package) and existing
+  capabilities (MediaRecorder video capture, MediaPipe eye-contact/smile/head
+  tracking, Web Audio loudness/pitch analysis, Web Speech & faster-whisper
+  transcription, IndexedDB draft recovery, PDF/TXT document reading, and exports).
+- Added a personalized 30-day Tech Presenter Training Curriculum with adaptive
+  presenter profiles, progress persistence, and one-click studio launch.
+- Added Daily Speaking Warm-Ups, Camera-Presenting Challenges, and dynamic
+  weakness-targeted improvement drills.
+- Upgraded the Camera Recording Studio with an on-lens built-in teleprompter
+  supporting auto-scroll, voice-synced highlighting, presenter bullet cues,
+  mirror mode, countdown timer, audio-only fallback, and editable transcripts.
+- Added a Technology News & Storytelling Practice desk with live RSS/HN feeds,
+  curated tech briefings, custom topic/URL parsing, and 4 presenter storyboards.
+- Added a built-in analytical presenter coaching engine fallback alongside
+  existing local LLM providers (Ollama, LM Studio, llama.cpp), plus local
+  background worker fallback when Redis/arq is not running.
+- Added Weekly Review analytics, reflection notes, enhanced Dual-Video
+  Side-by-Side Recording Comparison, and a responsive Mac + mobile UI shell.

README.md

@@ -0,0 +1,385 @@
+---
+title: Tech Presenter Coach
+emoji: 🎙️
+colorFrom: red
+colorTo: yellow
+sdk: docker
+app_port: 7860
+---
+
+![Speech-Machine Banner](./Speech_Machine_Banner.png)
+
+# Speech-Machine · Personal Tech Presenter Coach Edition
+
+Speech-Machine is an AI-assisted speech practice and review platform extended into a daily, responsive **Personal Technology Presenter Coach** for Mac and mobile phone browsers.
+
+## Personal Tech Presenter Coach Upgrades
+
+Built directly on [`SSusantAchary/speech-machine`](https://github.com/SSusantAchary/speech-machine) (Apache License 2.0 — see `LICENSE` and `NOTICE`), this edition preserves all core recording, transcription, MediaPipe delivery tracking, document reading, draft recovery, and analytics capabilities while adding:
+
+- **Personalized 30-Day Tech Presenter Curriculum (`/curriculum`)**: Customizable Presenter Profile (role, speaking track, target WPM zone, habits to fix) + 4 progressive training weeks (30 daily missions with warm-ups, camera challenges, teleprompter scripts, bullet cues, reflection notes, and auto-completion).
+- **Camera Studio with Built-In On-Lens Teleprompter (`/record`)**: Top-of-frame eye-line teleprompter supporting **Auto-Scroll** (WPM-calibrated), **Voice-Sync** word highlighting, and **Bullet Cue Cards**, plus mirror mode, font/opacity controls, 3–2–1 countdown, audio-only fallback, and unblocked browser session saving without requiring a local Whisper download first.
+- **Technology News & Storytelling Lab (`/tech-news`)**: Live RSS tech news feed (Ars Technica, Hacker News, The Verge Tech + curated briefings) and custom topic/URL storyboard builder across 4 presenter frameworks (*60s Breaking Tech Briefing*, *2-Min Deep-Dive Explainer*, *90s Contrarian Take*, *2-Min Builder Story*).
+- **Daily Warm-Ups, Targeted Weakness Drills & Camera Challenges (`/exercises`)**: Interactive 60s vocal/presence countdown warm-ups, weakness-matched drills driven by your recent WPM/filler/eye-contact telemetry, and on-camera presenter challenges.
+- **Built-In Smart Presenter Coach (`/session/[id]`)**: Works out-of-the-box with zero external LLM setup (and seamlessly upgrades to local Ollama / LM Studio / llama.cpp when running), plus inline transcript editing (`PATCH /sessions/{id}/transcript`) that recomputes scores and coaching on demand.
+- **Streaks, Weekly Reviews & Side-by-Side Video Comparison (`/progress`)**: Synchronized dual-video playback comparing Take A vs Take B, metric deltas, 365-day activity heatmap, and weekly presenter reflection journal.
+- **Mac + Mobile Phone Responsive Architecture**: Desktop top navigation + mobile safe-area bottom tab bar, with Next.js same-origin API proxying (`/api/backend/*`) so a single port (`:3000`) works cleanly across Mac and mobile browsers over LAN, Tailscale, or HTTPS tunnels.
+
+### Quick Start (Mac + Phone Browser)
+
+```bash
+./infra/scripts/run_presenter_coach.sh
+```
+
+- **On your Mac**: Open `http://localhost:3000`
+- **On your Phone (same Wi-Fi / Tailscale)**: Open `https://<your-mac-tailscale-domain>:3000` (note: mobile browsers require `https://` or `localhost` to grant camera/microphone `getUserMedia` access; `tailscale serve --https=443 http://localhost:3000` or Cloudflare Tunnel provides instant HTTPS on mobile).
+
+## Sample UI
+
+Below is a sample Speech-Machine screen showing the product layout and session statistics view.
+
+![Speech-Machine Sample UI](./Screenshot_Speech_Machine.png)
+
+## What It Does
+
+- Records practice videos in the browser with camera and microphone selection.
+- Uploads existing videos for asynchronous transcription and review.
+- Downloads transcript output as `.txt` and `.pdf`.
+- Saves full practice sessions with score, transcript, metrics, and review data.
+- Restores unsaved recording drafts from browser storage after refresh.
+- Tracks realtime speaking cues such as words per minute, filler words, pauses, and rolling captions.
+- Tracks delivery signals such as eye contact, smile, loudness, and head movement.
+- Supports a scrollable reading document panel during recording for `.pdf` and `.txt` files.
+- Highlights the current reading block during recording using live browser speech cues when supported.
+- Exports complete session bundles and supports video-only delete or full session delete.
+- Supports first-run local admin setup and email/password authentication.
+
+## Core Capabilities
+
+### Recording and review
+
+- Browser-based recording with MediaRecorder
+- Realtime preview and review playback
+- Draft recovery for unsaved recordings
+- Session comparison and score breakdown
+- Timeline markers for speaking issues and improvement points
+
+### Speech analysis
+
+- Final server-side transcription
+- Realtime browser speech cues where the Web Speech API is available
+- Average and realtime WPM
+- Filler-word detection
+- Long-pause and silence detection
+- Transcript search and filler highlighting
+
+### Delivery analysis
+
+- Eye-contact estimation using MediaPipe face landmarks
+- Smile and head stability metrics
+- Loudness tracking from the audio stream
+- Composite scoring across delivery, speech, and content
+
+### Guided reading
+
+- Upload a reading document during recording
+- Supported input: `.pdf`, `.txt`
+- Vertical teleprompter-style reading panel below the recorder
+- Live paragraph highlighting based on current spoken content when browser speech recognition is available
+
+## Platform Compatibility
+
+### Primary supported runtime
+
+The primary supported runtime is the Docker stack.
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| macOS | Supported | Best overall local development path with Docker Desktop |
+| Linux | Supported | Good fit for local and server deployment |
+| Windows | Supported | Use Docker Desktop; WSL2-backed setups are recommended |
+
+### Browser compatibility
+
+| Browser | Recording | Realtime speech cues | Notes |
+| --- | --- | --- | --- |
+| Chrome | Supported | Best support | Recommended browser |
+| Edge | Supported | Good support | Recommended browser |
+| Safari | Supported | Limited / browser-dependent | Recording path includes Safari-specific handling; Web Speech API support may be unavailable |
+| Firefox | Partial | Limited | Core UI works, but speech-recognition behavior depends on browser capabilities |
+
+### Desktop runtime note
+
+The repo also contains a desktop-oriented runtime foundation, but the default and recommended deployment path is still Docker. Optional `MLX Audio` support is macOS Apple Silicon oriented.
+
+## Minimum System Requirements
+
+These are practical minimums for local Docker usage, not hard-enforced limits.
+
+| Requirement | Minimum | Recommended |
+| --- | --- | --- |
+| CPU | 4 logical cores | 8 logical cores |
+| Memory | 8 GB RAM | 16 GB RAM |
+| Free disk | 10 GB | 20+ GB, especially when downloading transcription models |
+| Browser | Modern Chromium / Safari | Latest Chrome or Edge |
+| Camera / Mic | Required for recording mode | External mic recommended for better transcription quality |
+| Docker | Docker Desktop or Docker Engine + Compose | Latest stable |
+
+Notes:
+- Larger Whisper models need more RAM, disk, and transcription time.
+- GPU is optional. CPU-only operation is supported.
+- If you plan to keep multiple downloaded models locally, reserve additional disk space.
+
+## Supported Transcription Models
+
+### Docker / server backend
+
+The default backend is the built-in server backend using `faster-whisper==1.1.0`. Models are downloaded only when the user explicitly chooses `Download` in the UI.
+
+- `openai/whisper-tiny`
+- `openai/whisper-base`
+- `openai/whisper-small`
+- `openai/whisper-medium`
+- `openai/whisper-large-v3`
+- `openai/whisper-large-v3-turbo`
+
+### Optional MLX Audio backend
+
+Available only in the optional desktop-oriented path when `mlx-audio` is installed and the runtime is compatible.
+
+- `mlx-community/whisper-large-v3-turbo-asr-fp16`
+- `distil-whisper/distil-large-v3`
+- `mlx-community/Qwen3-ASR-1.7B-8bit`
+- `mlx-community/Qwen3-ForcedAligner-0.6B-8bit`
+- `mlx-community/parakeet-tdt-0.6b-v3`
+- `mlx-community/Voxtral-Mini-3B-2507-bf16`
+- `mlx-community/Voxtral-Mini-4B-Realtime-2602-4bit`
+- `mlx-community/Voxtral-Mini-4B-Realtime-2602-fp16`
+- `mlx-community/VibeVoice-ASR-bf16`
+
+## Latency Characteristics
+
+Speech-Machine does not ship a formal benchmark suite yet, so latency depends on browser, host CPU/GPU, selected model, and recording length.
+
+| Workflow | Expected behavior |
+| --- | --- |
+| Live recorder metrics | Near realtime in the browser |
+| Live face / delivery metrics | Near realtime on modern hardware |
+| Save session | Usually seconds, depending on file size and storage |
+| Final transcription | Seconds to minutes depending on video duration and model size |
+| Model download | One-time per model; depends on model size and network speed |
+
+Practical guidance:
+- `Whisper Tiny` and `Whisper Base` are the fastest options.
+- `Whisper Small` is a good default balance for local CPU usage.
+- `Whisper Medium`, `Large v3`, and `Large v3 Turbo` need more memory and longer completion time.
+
+## Tech Stack
+
+### Frontend
+
+- Next.js 14 App Router
+- React 18
+- TypeScript
+- Tailwind CSS
+- Zustand
+- Recharts
+- `idb` for IndexedDB draft persistence
+- `pdfjs-dist` for PDF text extraction
+- MediaPipe Tasks Vision
+- Web Audio API
+- Web Speech API
+
+### Backend
+
+- FastAPI
+- SQLAlchemy
+- PostgreSQL in Docker
+- SQLite in desktop-oriented local runtime mode
+- JWT authentication
+- Local file storage with optional S3-compatible storage
+- `ffmpeg` for audio extraction
+- `faster-whisper==1.1.0`
+- Optional `mlx-audio`
+- `huggingface_hub` for on-demand local model downloads
+
+### Tooling
+
+- Docker Compose
+- Vitest
+- Playwright
+- Pytest
+- Make
+
+## Architecture
+
+```mermaid
+flowchart LR
+    User([Speaker]) --> Browser
+
+    subgraph Client[Browser / Next.js]
+        Browser[Next.js web app]
+        Capture[MediaRecorder<br/>camera and microphone]
+        Live[MediaPipe + Web Audio<br/>live delivery metrics]
+        Drafts[(IndexedDB<br/>draft recovery)]
+        Browser --> Capture
+        Browser --> Live
+        Browser <--> Drafts
+    end
+
+    Browser <-->|HTTPS / JSON<br/>job polling| API
+
+    subgraph Services[Docker application services]
+        API[FastAPI API<br/>authentication and sessions]
+        Queue[(Redis<br/>arq job queue)]
+        Worker[Background worker]
+        Database[(PostgreSQL<br/>sessions and analytics)]
+        Storage[(Local or S3 storage<br/>video and documents)]
+
+        API <--> Database
+        API <--> Storage
+        API -->|enqueue transcription| Queue
+        Queue --> Worker
+        Worker <--> Storage
+        Worker --> Database
+    end
+
+    subgraph Intelligence[Local intelligence]
+        Media[ffmpeg]
+        ASR[faster-whisper<br/>or optional MLX Audio]
+        Coach[Ollama, LM Studio,<br/>or llama.cpp]
+        Media --> ASR
+    end
+
+    Worker --> Media
+    ASR -->|transcript and metrics| Worker
+    Worker -->|session context| Coach
+    Coach -->|structured coaching| Worker
+```
+
+Recordings and uploaded videos are validated by the API, stored locally or in S3-compatible storage, and queued through Redis. The worker extracts audio, runs transcription, computes analytics, and optionally requests structured coaching from a local LLM. The web app polls for job completion and renders the saved session, dashboard trends, and coaching feedback.
+
+See [the architecture guide](./docs/ARCHITECTURE.md) for the request lifecycle and security boundaries.
+
+## Repository Layout
+
+- `apps/web`: Next.js frontend
+- `apps/api`: FastAPI backend
+- `packages/shared`: shared types and scoring logic
+- `infra`: desktop runtime helpers
+- `docs`: packaging and supporting documentation
+
+## Quick Start
+
+### Recommended: Docker
+
+```bash
+cp .env.example .env
+make local-up
+```
+
+Open:
+
+- App: `http://localhost:3000`
+- API docs: `http://localhost:8000/docs`
+
+On first launch, open the app and create the local admin account in the setup screen.
+
+You can also create the first local admin from the terminal:
+
+```bash
+curl -X POST http://localhost:8000/setup \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@example.com","password":"change-me-strong"}'
+```
+
+Then run a local smoke check:
+
+```bash
+make local-smoke
+```
+
+See [docs/local-machine.md](./docs/local-machine.md) for the full local workflow.
+
+### Local development without Docker
+
+#### API
+
+```bash
+cd apps/api
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+#### Web
+
+```bash
+cd apps/web
+npm install
+npm run dev
+```
+
+## Build and Test
+
+```bash
+make local-build
+```
+
+```bash
+make check
+```
+
+## Lines of Code
+
+Source snapshot as of March 22, 2026, excluding `node_modules`, `.next`, caches, and lockfiles:
+
+| Area | Files | Approx. LOC |
+| --- | --- | --- |
+| API | 17 | 2,370 |
+| Web | 36 | 4,444 |
+| Shared | 4 | 290 |
+| Infra | 4 | 263 |
+| Total app source | 61 | 7,367 |
+
+
+
+## Current Feature Set
+
+- Browser recording and uploaded-video transcription
+- Transcript download in `.txt` and `.pdf`
+- Session export bundle
+- Session comparison
+- Full session delete and video-only delete
+- Reading-document upload and guided reading panel
+- Draft recovery
+- Model download-on-demand from the UI
+- User-defined practice goals with live progress and goal-aware AI coaching
+- Docker-first local deployment
+
+## Planned / Upcoming Upgrades
+
+- Better progress reporting for long model downloads
+- Broader browser support around live speech cues
+- Stronger progress reporting for queued transcription workloads
+- More production deployment presets
+- Native desktop shell packaging
+- Stronger benchmarking and latency reporting
+- Richer document guidance and reading analytics
+
+## License
+
+This project is licensed under the Apache License 2.0.
+
+High-level summary:
+- You may use, modify, and distribute the software.
+- You must preserve copyright and license notices.
+- Changes should be documented when redistributing modified versions.
+- The software is provided on an “AS IS” basis without warranties.
+
+See [LICENSE](./LICENSE) for the full license text.
+
+## Developer
+
+Developed by **Susant Achary**.

apps/api/Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.11-slim
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ffmpeg build-essential libsndfile1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY src ./src
+COPY alembic.ini ./alembic.ini
+COPY migrations ./migrations
+COPY docker-entrypoint.sh ./docker-entrypoint.sh
+RUN chmod +x ./docker-entrypoint.sh
+
+ENV PYTHONPATH=/app/src
+
+ENTRYPOINT ["./docker-entrypoint.sh"]
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

apps/api/alembic.ini

@@ -0,0 +1,38 @@
+[alembic]
+script_location = migrations
+prepend_sys_path = .
+sqlalchemy.url =
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

apps/api/docker-entrypoint.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+set -e
+
+if [ "${RUN_MIGRATIONS:-true}" = "true" ]; then
+  alembic upgrade head
+fi
+
+exec "$@"

apps/api/migrations/env.py

@@ -0,0 +1,45 @@
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from app.config import settings
+from app.db import Base
+from app import models  # noqa: F401
+
+config = context.config
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=settings.database_url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    configuration = config.get_section(config.config_ini_section, {})
+    configuration["sqlalchemy.url"] = settings.database_url
+    connectable = engine_from_config(
+        configuration,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

apps/api/migrations/script.py.mako

@@ -0,0 +1,22 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

apps/api/migrations/versions/20260607_0001_initial_foundation.py

@@ -0,0 +1,141 @@
+"""initial foundation schema
+
+Revision ID: 20260607_0001
+Revises:
+Create Date: 2026-06-07
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "20260607_0001"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "users",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("email", sa.String(length=255), nullable=False),
+        sa.Column("hashed_password", sa.String(length=255), nullable=False),
+        sa.Column("is_admin", sa.Boolean(), nullable=False, server_default=sa.false()),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_users_id"), "users", ["id"], unique=False)
+    op.create_index(op.f("ix_users_email"), "users", ["email"], unique=True)
+
+    op.create_table(
+        "refresh_tokens",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("jti_hash", sa.String(length=64), nullable=False),
+        sa.Column("expires_at", sa.DateTime(), nullable=False),
+        sa.Column("revoked_at", sa.DateTime(), nullable=True),
+        sa.Column("replaced_by_jti_hash", sa.String(length=64), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_refresh_tokens_id"), "refresh_tokens", ["id"], unique=False)
+    op.create_index(op.f("ix_refresh_tokens_user_id"), "refresh_tokens", ["user_id"], unique=False)
+    op.create_index(op.f("ix_refresh_tokens_jti_hash"), "refresh_tokens", ["jti_hash"], unique=True)
+
+    op.create_table(
+        "sessions",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("title", sa.String(length=255), nullable=True),
+        sa.Column("mode", sa.String(length=80), nullable=True),
+        sa.Column("prompt", sa.Text(), nullable=True),
+        sa.Column("goal", sa.String(length=255), nullable=True),
+        sa.Column("started_at", sa.DateTime(), nullable=True),
+        sa.Column("ended_at", sa.DateTime(), nullable=True),
+        sa.Column("duration_ms", sa.Integer(), nullable=True),
+        sa.Column("wpm_avg", sa.Float(), nullable=True),
+        sa.Column("filler_count", sa.Integer(), nullable=True),
+        sa.Column("eye_contact_pct", sa.Float(), nullable=True),
+        sa.Column("video_path", sa.String(length=1024), nullable=True),
+        sa.Column("document_path", sa.String(length=1024), nullable=True),
+        sa.Column("document_name", sa.String(length=255), nullable=True),
+        sa.Column("document_mime_type", sa.String(length=255), nullable=True),
+        sa.Column("document_blocks_json", sa.Text(), nullable=True),
+        sa.Column("transcription_status", sa.String(length=32), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_sessions_id"), "sessions", ["id"], unique=False)
+
+    op.create_table(
+        "metrics_timeseries",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("session_id", sa.Integer(), nullable=False),
+        sa.Column("t", sa.Integer(), nullable=False),
+        sa.Column("wpm", sa.Float(), nullable=True),
+        sa.Column("rms", sa.Float(), nullable=True),
+        sa.Column("eye_contact", sa.Float(), nullable=True),
+        sa.Column("smile", sa.Float(), nullable=True),
+        sa.Column("yaw", sa.Float(), nullable=True),
+        sa.Column("pitch", sa.Float(), nullable=True),
+        sa.Column("roll", sa.Float(), nullable=True),
+        sa.Column("filler_count", sa.Integer(), nullable=True),
+        sa.Column("pause_ms", sa.Integer(), nullable=True),
+        sa.ForeignKeyConstraint(["session_id"], ["sessions.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_metrics_timeseries_id"), "metrics_timeseries", ["id"], unique=False)
+
+    op.create_table(
+        "scores",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("session_id", sa.Integer(), nullable=False),
+        sa.Column("data", sa.JSON(), nullable=False),
+        sa.ForeignKeyConstraint(["session_id"], ["sessions.id"]),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("session_id"),
+    )
+    op.create_index(op.f("ix_scores_id"), "scores", ["id"], unique=False)
+
+    op.create_table(
+        "tags",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("session_id", sa.Integer(), nullable=False),
+        sa.Column("name", sa.String(length=80), nullable=False),
+        sa.ForeignKeyConstraint(["session_id"], ["sessions.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_tags_id"), "tags", ["id"], unique=False)
+
+    op.create_table(
+        "transcript_segments",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("session_id", sa.Integer(), nullable=False),
+        sa.Column("start_ms", sa.Integer(), nullable=False),
+        sa.Column("end_ms", sa.Integer(), nullable=False),
+        sa.Column("text", sa.Text(), nullable=False),
+        sa.ForeignKeyConstraint(["session_id"], ["sessions.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_transcript_segments_id"), "transcript_segments", ["id"], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_transcript_segments_id"), table_name="transcript_segments")
+    op.drop_table("transcript_segments")
+    op.drop_index(op.f("ix_tags_id"), table_name="tags")
+    op.drop_table("tags")
+    op.drop_index(op.f("ix_scores_id"), table_name="scores")
+    op.drop_table("scores")
+    op.drop_index(op.f("ix_metrics_timeseries_id"), table_name="metrics_timeseries")
+    op.drop_table("metrics_timeseries")
+    op.drop_index(op.f("ix_sessions_id"), table_name="sessions")
+    op.drop_table("sessions")
+    op.drop_index(op.f("ix_refresh_tokens_jti_hash"), table_name="refresh_tokens")
+    op.drop_index(op.f("ix_refresh_tokens_user_id"), table_name="refresh_tokens")
+    op.drop_index(op.f("ix_refresh_tokens_id"), table_name="refresh_tokens")
+    op.drop_table("refresh_tokens")
+    op.drop_index(op.f("ix_users_email"), table_name="users")
+    op.drop_index(op.f("ix_users_id"), table_name="users")
+    op.drop_table("users")

apps/api/migrations/versions/20260608_0002_analytics_coaching.py

@@ -0,0 +1,117 @@
+"""add analytics and coaching tables
+
+Revision ID: 20260608_0002
+Revises: 20260607_0001
+Create Date: 2026-06-08
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "20260608_0002"
+down_revision = "20260607_0001"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "session_metrics",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("session_id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("recorded_at", sa.DateTime(), nullable=False),
+        sa.Column("duration_seconds", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("word_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("wpm", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("filler_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("filler_rate", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("pause_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("unique_word_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("vocabulary_density", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("eye_contact_score", sa.Float(), nullable=True),
+        sa.Column("smile_score", sa.Float(), nullable=True),
+        sa.Column("head_stability_score", sa.Float(), nullable=True),
+        sa.Column("loudness_score", sa.Float(), nullable=True),
+        sa.Column("speech_score", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("delivery_score", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("overall_score", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("filler_breakdown", sa.JSON(), nullable=True),
+        sa.Column("wpm_timeline", sa.JSON(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(["session_id"], ["sessions.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("session_id"),
+    )
+    op.create_index(op.f("ix_session_metrics_id"), "session_metrics", ["id"], unique=False)
+    op.create_index(op.f("ix_session_metrics_session_id"), "session_metrics", ["session_id"], unique=False)
+    op.create_index(op.f("ix_session_metrics_user_id"), "session_metrics", ["user_id"], unique=False)
+    op.create_index("ix_session_metrics_user_date", "session_metrics", ["user_id", "recorded_at"], unique=False)
+
+    op.create_table(
+        "daily_aggregates",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("practice_date", sa.Date(), nullable=False),
+        sa.Column("session_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("total_duration_seconds", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("avg_wpm", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("avg_filler_rate", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("avg_overall_score", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("avg_speech_score", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("avg_delivery_score", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("best_overall_score", sa.Float(), nullable=False, server_default="0"),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("user_id", "practice_date", name="uq_daily_aggregates_user_date"),
+    )
+    op.create_index(op.f("ix_daily_aggregates_id"), "daily_aggregates", ["id"], unique=False)
+    op.create_index(op.f("ix_daily_aggregates_user_id"), "daily_aggregates", ["user_id"], unique=False)
+    op.create_index("ix_daily_aggregates_user_date", "daily_aggregates", ["user_id", "practice_date"], unique=False)
+
+    op.create_table(
+        "coaching_feedback",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("session_id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("status", sa.String(length=20), nullable=False, server_default="pending"),
+        sa.Column("model_used", sa.String(length=100), nullable=True),
+        sa.Column("generation_time_ms", sa.Integer(), nullable=True),
+        sa.Column("summary", sa.Text(), nullable=True),
+        sa.Column("strengths", sa.JSON(), nullable=True),
+        sa.Column("improvements", sa.JSON(), nullable=True),
+        sa.Column("drills", sa.JSON(), nullable=True),
+        sa.Column("practice_plan", sa.JSON(), nullable=True),
+        sa.Column("raw_response", sa.Text(), nullable=True),
+        sa.Column("compared_to_session_id", sa.Integer(), nullable=True),
+        sa.Column("trend_context", sa.JSON(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=True),
+        sa.Column("error_message", sa.Text(), nullable=True),
+        sa.ForeignKeyConstraint(["session_id"], ["sessions.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("session_id"),
+    )
+    op.create_index(op.f("ix_coaching_feedback_id"), "coaching_feedback", ["id"], unique=False)
+    op.create_index(op.f("ix_coaching_feedback_session_id"), "coaching_feedback", ["session_id"], unique=False)
+    op.create_index(op.f("ix_coaching_feedback_user_id"), "coaching_feedback", ["user_id"], unique=False)
+    op.create_index("ix_coaching_feedback_user_created", "coaching_feedback", ["user_id", "created_at"], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index("ix_coaching_feedback_user_created", table_name="coaching_feedback")
+    op.drop_index(op.f("ix_coaching_feedback_user_id"), table_name="coaching_feedback")
+    op.drop_index(op.f("ix_coaching_feedback_session_id"), table_name="coaching_feedback")
+    op.drop_index(op.f("ix_coaching_feedback_id"), table_name="coaching_feedback")
+    op.drop_table("coaching_feedback")
+
+    op.drop_index("ix_daily_aggregates_user_date", table_name="daily_aggregates")
+    op.drop_index(op.f("ix_daily_aggregates_user_id"), table_name="daily_aggregates")
+    op.drop_index(op.f("ix_daily_aggregates_id"), table_name="daily_aggregates")
+    op.drop_table("daily_aggregates")
+
+    op.drop_index("ix_session_metrics_user_date", table_name="session_metrics")
+    op.drop_index(op.f("ix_session_metrics_user_id"), table_name="session_metrics")
+    op.drop_index(op.f("ix_session_metrics_session_id"), table_name="session_metrics")
+    op.drop_index(op.f("ix_session_metrics_id"), table_name="session_metrics")
+    op.drop_table("session_metrics")

apps/api/migrations/versions/20260904_0003_user_goals.py

@@ -0,0 +1,41 @@
+"""add user goals
+
+Revision ID: 20260904_0003
+Revises: 20260608_0002
+Create Date: 2026-09-04
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "20260904_0003"
+down_revision = "20260608_0002"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "user_goals",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("metric_name", sa.String(length=50), nullable=False),
+        sa.Column("comparison", sa.String(length=10), nullable=False),
+        sa.Column("target_value", sa.Float(), nullable=False),
+        sa.Column("target_upper", sa.Float(), nullable=True),
+        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.true()),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("user_id", "metric_name", name="uq_user_goals_user_metric"),
+    )
+    op.create_index(op.f("ix_user_goals_id"), "user_goals", ["id"], unique=False)
+    op.create_index(op.f("ix_user_goals_user_id"), "user_goals", ["user_id"], unique=False)
+    op.create_index("ix_user_goals_user_active", "user_goals", ["user_id", "is_active"], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index("ix_user_goals_user_active", table_name="user_goals")
+    op.drop_index(op.f("ix_user_goals_user_id"), table_name="user_goals")
+    op.drop_index(op.f("ix_user_goals_id"), table_name="user_goals")
+    op.drop_table("user_goals")

apps/api/mypy.ini

@@ -0,0 +1,4 @@
+[mypy]
+python_version = 3.11
+ignore_missing_imports = True
+ignore_errors = True

apps/api/requirements-desktop.txt

@@ -0,0 +1,18 @@
+fastapi==0.111.0
+uvicorn[standard]==0.30.0
+sqlalchemy==2.0.30
+pydantic==2.7.2
+pydantic-settings==2.2.1
+email-validator==2.2.0
+python-jose==3.3.0
+passlib[bcrypt]==1.7.4
+python-multipart==0.0.9
+aiofiles==23.2.1
+faster-whisper==1.1.0
+httpx==0.27.0
+requests==2.32.3
+Cython
+packaging
+huggingface_hub==0.24.7
+nemo_toolkit[asr]
+mlx-audio

apps/api/requirements-dev.txt

@@ -0,0 +1,4 @@
+-r requirements.txt
+ruff==0.5.7
+mypy==1.11.1
+pytest-cov==5.0.0

apps/api/requirements.txt

@@ -0,0 +1,21 @@
+fastapi==0.111.0
+uvicorn[standard]==0.30.0
+sqlalchemy==2.0.30
+psycopg2-binary==2.9.9
+pydantic==2.7.2
+pydantic-settings==2.2.1
+email-validator==2.2.0
+python-jose==3.3.0
+passlib[bcrypt]==1.7.4
+python-multipart==0.0.9
+aiofiles==23.2.1
+boto3==1.34.107
+alembic==1.13.2
+arq==0.26.1
+redis[hiredis]==5.0.8
+faster-whisper==1.1.0
+pytest==8.2.1
+httpx==0.27.0
+requests==2.32.3
+Cython
+packaging

apps/api/ruff.toml

@@ -0,0 +1,9 @@
+target-version = "py311"
+line-length = 110
+
+[lint]
+select = ["E", "F"]
+ignore = ["E402", "E501"]
+
+[lint.per-file-ignores]
+"tests/**/*.py" = ["S101"]

apps/api/src/app/auth.py

@@ -0,0 +1,277 @@
+import hashlib
+import uuid
+from datetime import datetime, timedelta
+
+import bcrypt
+from fastapi import Body, Cookie, Depends, Header, HTTPException, Query, Response, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from app import models
+from app.config import settings
+from app.db import get_db
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/login", auto_error=False)
+REFRESH_COOKIE_NAME = "refresh_token"
+ACCESS_HEADER_NAME = "X-Presenter-Token"
+REFRESH_HEADER_NAME = "X-Refresh-Token"
+
+
+class TokenPayload(BaseModel):
+    sub: str
+    email: str | None = None
+    role: str = "user"
+    jti: str
+    type: str
+
+
+def hash_password(password: str) -> str:
+    return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt(rounds=12)).decode("utf-8")
+
+
+def verify_password(password: str, hashed_password: str) -> bool:
+    return bcrypt.checkpw(password.encode("utf-8"), hashed_password.encode("utf-8"))
+
+
+def _utcnow() -> datetime:
+    return datetime.utcnow()
+
+
+def _hash_jti(jti: str) -> str:
+    return hashlib.sha256(jti.encode("utf-8")).hexdigest()
+
+
+def _token_expire_delta(token_type: str) -> timedelta:
+    if token_type == "refresh":
+        return timedelta(days=settings.refresh_token_expire_days)
+    return timedelta(minutes=settings.access_token_expire_minutes)
+
+
+def _create_token(user: models.User, token_type: str, jti: str | None = None) -> tuple[str, str, datetime]:
+    token_jti = jti or str(uuid.uuid4())
+    expires_at = _utcnow() + _token_expire_delta(token_type)
+    payload = {
+        "sub": str(user.id),
+        "email": user.email,
+        "role": "admin" if user.is_admin else "user",
+        "iat": _utcnow(),
+        "exp": expires_at,
+        "jti": token_jti,
+        "type": token_type,
+    }
+    token = jwt.encode(payload, settings.jwt_secret, algorithm=settings.jwt_algorithm)
+    return token, token_jti, expires_at
+
+
+def create_access_token(user: models.User) -> str:
+    token, _jti, _expires_at = _create_token(user, "access")
+    return token
+
+
+def create_refresh_token(db: Session, user: models.User) -> str:
+    token, jti, expires_at = _create_token(user, "refresh")
+    db.add(
+        models.RefreshToken(
+            user_id=user.id,
+            jti_hash=_hash_jti(jti),
+            expires_at=expires_at,
+        )
+    )
+    db.commit()
+    return token
+
+
+def set_refresh_cookie(response: Response, token: str) -> None:
+    response.set_cookie(
+        key=REFRESH_COOKIE_NAME,
+        value=token,
+        httponly=True,
+        secure=settings.cookie_secure,
+        samesite="lax",
+        max_age=settings.refresh_token_expire_days * 24 * 60 * 60,
+        path=settings.cookie_path,
+    )
+
+
+def clear_refresh_cookie(response: Response) -> None:
+    response.delete_cookie(
+        key=REFRESH_COOKIE_NAME,
+        httponly=True,
+        secure=settings.cookie_secure,
+        samesite="lax",
+        path=settings.cookie_path,
+    )
+
+
+def decode_token(token: str, expected_type: str = "access") -> TokenPayload:
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid or expired token",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(
+            token,
+            settings.jwt_secret,
+            algorithms=[settings.jwt_algorithm],
+            options={"require_exp": True, "require_iat": True},
+        )
+    except JWTError as exc:
+        raise credentials_exception from exc
+
+    if payload.get("type") != expected_type:
+        raise credentials_exception
+
+    try:
+        return TokenPayload(
+            sub=str(payload["sub"]),
+            email=payload.get("email"),
+            role=payload.get("role", "user"),
+            jti=str(payload["jti"]),
+            type=str(payload["type"]),
+        )
+    except (KeyError, ValueError) as exc:
+        raise credentials_exception from exc
+
+
+def authenticate_user(db: Session, email: str, password: str) -> models.User | None:
+    user = db.query(models.User).filter(models.User.email == email).first()
+    if not user or not verify_password(password, user.hashed_password):
+        return None
+    return user
+
+
+def issue_token_pair(db: Session, response: Response, user: models.User) -> dict:
+    access_token = create_access_token(user)
+    refresh_token = create_refresh_token(db, user)
+    set_refresh_cookie(response, refresh_token)
+    return {
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+        "token_type": "bearer",
+        "expires_in": settings.access_token_expire_minutes * 60,
+        "user": {"id": user.id, "email": user.email, "is_admin": user.is_admin},
+    }
+
+
+def rotate_refresh_token(
+    db: Session,
+    response: Response,
+    refresh_token: str | None,
+) -> dict:
+    if not refresh_token:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing refresh token")
+
+    payload = decode_token(refresh_token, expected_type="refresh")
+    token_row = (
+        db.query(models.RefreshToken)
+        .filter(models.RefreshToken.jti_hash == _hash_jti(payload.jti))
+        .first()
+    )
+    if token_row is None or token_row.revoked_at is not None or token_row.expires_at <= _utcnow():
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid refresh token")
+
+    try:
+        user_id = int(payload.sub)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid refresh token") from exc
+
+    user = db.query(models.User).filter(models.User.id == user_id).first()
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid refresh token")
+
+    access_token = create_access_token(user)
+    new_refresh_token, new_jti, new_expires_at = _create_token(user, "refresh")
+    token_row.revoked_at = _utcnow()
+    token_row.replaced_by_jti_hash = _hash_jti(new_jti)
+    db.add(
+        models.RefreshToken(
+            user_id=user.id,
+            jti_hash=_hash_jti(new_jti),
+            expires_at=new_expires_at,
+        )
+    )
+    db.commit()
+    set_refresh_cookie(response, new_refresh_token)
+    return {
+        "access_token": access_token,
+        "refresh_token": new_refresh_token,
+        "token_type": "bearer",
+        "expires_in": settings.access_token_expire_minutes * 60,
+        "user": {"id": user.id, "email": user.email, "is_admin": user.is_admin},
+    }
+
+
+def revoke_refresh_token(db: Session, response: Response, refresh_token: str | None) -> None:
+    if refresh_token:
+        try:
+            payload = decode_token(refresh_token, expected_type="refresh")
+        except HTTPException:
+            payload = None
+        if payload is not None:
+            token_row = (
+                db.query(models.RefreshToken)
+                .filter(models.RefreshToken.jti_hash == _hash_jti(payload.jti))
+                .first()
+            )
+            if token_row is not None and token_row.revoked_at is None:
+                token_row.revoked_at = _utcnow()
+                db.commit()
+    clear_refresh_cookie(response)
+
+
+def get_current_user(
+    db: Session = Depends(get_db),
+    bearer_token: str | None = Depends(oauth2_scheme),
+    header_token: str | None = Header(default=None, alias=ACCESS_HEADER_NAME),
+    query_token: str | None = Query(default=None, alias="_pt"),
+) -> models.User:
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    candidates = [tok for tok in (header_token, query_token, bearer_token) if tok]
+    if not candidates:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    payload: TokenPayload | None = None
+    last_error: HTTPException = credentials_exception
+    for candidate in candidates:
+        try:
+            payload = decode_token(candidate, expected_type="access")
+            break
+        except HTTPException as exc:
+            last_error = exc
+
+    if payload is None:
+        raise last_error
+
+    try:
+        user_id = int(payload.sub)
+    except ValueError as exc:
+        raise credentials_exception from exc
+
+    user = db.query(models.User).filter(models.User.id == user_id).first()
+    if user is None:
+        raise credentials_exception
+    return user
+
+
+def get_refresh_cookie(
+    refresh_token: str | None = Cookie(default=None, alias=REFRESH_COOKIE_NAME),
+    header_refresh_token: str | None = Header(default=None, alias=REFRESH_HEADER_NAME),
+    body_payload: dict | None = Body(default=None),
+) -> str | None:
+    body_token = None
+    if isinstance(body_payload, dict):
+        raw = body_payload.get("refresh_token")
+        if isinstance(raw, str) and raw.strip():
+            body_token = raw.strip()
+    return refresh_token or header_refresh_token or body_token

apps/api/src/app/config.py

@@ -0,0 +1,68 @@
+import json
+
+from pydantic import ConfigDict
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    model_config = ConfigDict(env_prefix="", case_sensitive=False)
+
+    database_url: str = "sqlite:///./local.db"
+    jwt_secret: str = "change-me"
+    jwt_algorithm: str = "HS256"
+    access_token_expire_minutes: int = 15
+    refresh_token_expire_days: int = 7
+    cookie_path: str = "/auth"
+    environment: str = "development"
+    cors_origins: str = "http://localhost:3000"
+    max_upload_mb: int = 500
+    redis_host: str = "localhost"
+    redis_port: int = 6379
+    storage_backend: str = "local"
+    local_only_mode: bool = False
+    local_admin_email: str = "admin@example.local"
+    local_admin_password: str = ""
+    storage_dir: str = "./data/storage"
+    s3_endpoint: str | None = None
+    s3_access_key: str | None = None
+    s3_secret_key: str | None = None
+    s3_bucket: str | None = None
+    s3_region: str | None = None
+    transcription_backend: str = "server"
+    whisper_model: str = "small"
+    whisper_device: str = "cpu"
+    mlx_audio_model: str = "mlx-community/parakeet-tdt-0.6b-v3"
+    ollama_base_url: str = "http://127.0.0.1:11434"
+    lmstudio_base_url: str = "http://127.0.0.1:1234/v1"
+    llama_cpp_base_url: str = "http://127.0.0.1:8080"
+    local_engine_timeout_seconds: float = 0.75
+    coaching_enabled: bool = True
+    coaching_provider: str = "auto"
+    coaching_fallback_builtin: bool = True
+    coaching_model: str = "llama3.2:3b"
+    coaching_timeout_seconds: float = 90
+    coaching_max_transcript_chars: int = 8000
+    use_local_worker_fallback: bool = True
+
+    @property
+    def cors_origin_list(self) -> list[str]:
+        value = self.cors_origins.strip()
+        if value.startswith("["):
+            try:
+                parsed = json.loads(value)
+            except json.JSONDecodeError:
+                parsed = None
+            if isinstance(parsed, list):
+                return [str(origin).strip() for origin in parsed if str(origin).strip()]
+        return [origin.strip() for origin in value.split(",") if origin.strip()]
+
+    @property
+    def max_upload_bytes(self) -> int:
+        return self.max_upload_mb * 1024 * 1024
+
+    @property
+    def cookie_secure(self) -> bool:
+        return self.environment.lower() == "production"
+
+
+settings = Settings()

apps/api/src/app/db.py

@@ -0,0 +1,26 @@
+from sqlalchemy import create_engine
+from sqlalchemy.engine.url import make_url
+from sqlalchemy.orm import declarative_base, sessionmaker
+
+from app.config import settings
+
+normalized_db_url = settings.database_url
+if normalized_db_url.startswith("postgres://"):
+    normalized_db_url = normalized_db_url.replace("postgres://", "postgresql://", 1)
+
+url = make_url(normalized_db_url)
+connect_args = {}
+if url.drivername.startswith("sqlite"):
+    connect_args = {"check_same_thread": False}
+
+engine = create_engine(normalized_db_url, pool_pre_ping=True, connect_args=connect_args)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+Base = declarative_base()
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

apps/api/src/app/hf_models.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import inspect
+import json
+import re
+import shutil
+from pathlib import Path
+from typing import Any, Callable
+
+from app.config import settings
+
+SERVER_BACKEND = "server"
+MLX_AUDIO_BACKEND = "mlx_audio"
+DOWNLOAD_MARKER = ".sparks-model-download.json"
+
+SERVER_WHISPER_MODELS: tuple[dict[str, str], ...] = (
+    {
+        "id": "openai/whisper-tiny",
+        "name": "Whisper Tiny",
+        "repo_id": "openai/whisper-tiny",
+        "runtime_model_id": "tiny",
+        "description": "OpenAI Whisper Tiny served through the faster-whisper runtime.",
+        "languages": "99+ languages",
+        "backend": SERVER_BACKEND,
+    },
+    {
+        "id": "openai/whisper-base",
+        "name": "Whisper Base",
+        "repo_id": "openai/whisper-base",
+        "runtime_model_id": "base",
+        "description": "OpenAI Whisper Base served through the faster-whisper runtime.",
+        "languages": "99+ languages",
+        "backend": SERVER_BACKEND,
+    },
+    {
+        "id": "openai/whisper-small",
+        "name": "Whisper Small",
+        "repo_id": "openai/whisper-small",
+        "runtime_model_id": "small",
+        "description": "OpenAI Whisper Small served through the faster-whisper runtime.",
+        "languages": "99+ languages",
+        "backend": SERVER_BACKEND,
+    },
+    {
+        "id": "openai/whisper-medium",
+        "name": "Whisper Medium",
+        "repo_id": "openai/whisper-medium",
+        "runtime_model_id": "medium",
+        "description": "OpenAI Whisper Medium served through the faster-whisper runtime.",
+        "languages": "99+ languages",
+        "backend": SERVER_BACKEND,
+    },
+    {
+        "id": "openai/whisper-large-v3",
+        "name": "Whisper Large v3",
+        "repo_id": "openai/whisper-large-v3",
+        "runtime_model_id": "large-v3",
+        "description": "OpenAI Whisper Large v3 served through the faster-whisper runtime.",
+        "languages": "99+ languages",
+        "backend": SERVER_BACKEND,
+    },
+    {
+        "id": "openai/whisper-large-v3-turbo",
+        "name": "Whisper Large v3 Turbo",
+        "repo_id": "openai/whisper-large-v3-turbo",
+        "runtime_model_id": "turbo",
+        "description": "OpenAI Whisper Large v3 Turbo served through the faster-whisper runtime.",
+        "languages": "99+ languages",
+        "backend": SERVER_BACKEND,
+    },
+)
+
+MLX_AUDIO_STT_MODELS: tuple[dict[str, str], ...] = (
+    {
+        "id": "mlx-community/whisper-large-v3-turbo-asr-fp16",
+        "name": "Whisper",
+        "repo_id": "mlx-community/whisper-large-v3-turbo-asr-fp16",
+        "description": "OpenAI's robust speech-to-text model for multilingual transcription.",
+        "languages": "99+ languages",
+        "backend": MLX_AUDIO_BACKEND,
+    },
+    {
+        "id": "distil-whisper/distil-large-v3",
+        "name": "Distil-Whisper",
+        "repo_id": "distil-whisper/distil-large-v3",
+        "description": "Distilled Whisper variant optimized for faster English transcription.",
+        "languages": "English",
+        "backend": MLX_AUDIO_BACKEND,
+    },
+    {
+        "id": "mlx-community/Qwen3-ASR-1.7B-8bit",
+        "name": "Qwen3-ASR",
+        "repo_id": "mlx-community/Qwen3-ASR-1.7B-8bit",
+        "description": "Alibaba's multilingual ASR model for speech recognition across major languages.",
+        "languages": "ZH, EN, JA, KO, and more",
+        "backend": MLX_AUDIO_BACKEND,
+    },
+    {
+        "id": "mlx-community/Qwen3-ForcedAligner-0.6B-8bit",
+        "name": "Qwen3-ForcedAligner",
+        "repo_id": "mlx-community/Qwen3-ForcedAligner-0.6B-8bit",
+        "description": "Word-level audio alignment model for timestamp refinement and transcript sync.",
+        "languages": "ZH, EN, JA, KO, and more",
+        "backend": MLX_AUDIO_BACKEND,
+    },
+    {
+        "id": "mlx-community/parakeet-tdt-0.6b-v3",
+        "name": "Parakeet",
+        "repo_id": "mlx-community/parakeet-tdt-0.6b-v3",
+        "description": "NVIDIA's accurate speech recognizer with strong multilingual coverage.",
+        "languages": "25 European languages",
+        "backend": MLX_AUDIO_BACKEND,
+    },
+    {
+        "id": "mlx-community/Voxtral-Mini-3B-2507-bf16",
+        "name": "Voxtral",
+        "repo_id": "mlx-community/Voxtral-Mini-3B-2507-bf16",
+        "description": "Mistral's compact speech model for general-purpose transcription.",
+        "languages": "Multiple languages",
+        "backend": MLX_AUDIO_BACKEND,
+    },
+    {
+        "id": "mlx-community/Voxtral-Mini-4B-Realtime-2602-4bit",
+        "name": "Voxtral Realtime 4bit",
+        "repo_id": "mlx-community/Voxtral-Mini-4B-Realtime-2602-4bit",
+        "description": "Streaming-friendly Voxtral realtime model quantized for lighter local use.",
+        "languages": "Multiple languages",
+        "backend": MLX_AUDIO_BACKEND,
+    },
+    {
+        "id": "mlx-community/Voxtral-Mini-4B-Realtime-2602-fp16",
+        "name": "Voxtral Realtime fp16",
+        "repo_id": "mlx-community/Voxtral-Mini-4B-Realtime-2602-fp16",
+        "description": "Higher precision realtime Voxtral transcription model for local speech capture.",
+        "languages": "Multiple languages",
+        "backend": MLX_AUDIO_BACKEND,
+    },
+    {
+        "id": "mlx-community/VibeVoice-ASR-bf16",
+        "name": "VibeVoice-ASR",
+        "repo_id": "mlx-community/VibeVoice-ASR-bf16",
+        "description": "Microsoft's ASR model with diarization and timestamp support.",
+        "languages": "Multiple languages",
+        "backend": MLX_AUDIO_BACKEND,
+    },
+)
+
+
+def get_models_root() -> Path:
+    storage_dir = Path(settings.storage_dir).expanduser()
+    return storage_dir.parent / "models" / "hf"
+
+
+def _sanitize_repo_id(repo_id: str) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]+", "-", repo_id).strip("-")
+
+
+def _model_dir(repo_id: str) -> Path:
+    return get_models_root() / _sanitize_repo_id(repo_id)
+
+
+def _download_marker_path(repo_id: str) -> Path:
+    return _model_dir(repo_id) / DOWNLOAD_MARKER
+
+
+def _is_model_downloaded(repo_id: str) -> bool:
+    model_dir = _model_dir(repo_id)
+    return model_dir.exists() and _download_marker_path(repo_id).exists()
+
+
+def _build_model_status(model: dict[str, str]) -> dict[str, Any]:
+    local_path = str(_model_dir(model["repo_id"])) if _is_model_downloaded(model["repo_id"]) else None
+    return {
+        "id": model["id"],
+        "name": model["name"],
+        "repo_id": model["repo_id"],
+        "description": model["description"],
+        "languages": model["languages"],
+        "available": local_path is not None,
+        "local_path": local_path,
+    }
+
+
+def _prepare_model_dir(repo_id: str) -> Path:
+    target_dir = _model_dir(repo_id)
+    target_dir.parent.mkdir(parents=True, exist_ok=True)
+    if target_dir.exists() and not _download_marker_path(repo_id).exists():
+        shutil.rmtree(target_dir, ignore_errors=True)
+    return target_dir
+
+
+def _finalize_download(repo_id: str) -> None:
+    _download_marker_path(repo_id).write_text(
+        json.dumps({"repo_id": repo_id}, indent=2),
+        encoding="utf-8",
+    )
+
+
+def _download_with_marker(model: dict[str, Any], downloader: Callable[[Path], None]) -> dict[str, Any]:
+    if _is_model_downloaded(model["repo_id"]):
+        return _build_model_status(model)
+
+    target_dir = _prepare_model_dir(model["repo_id"])
+
+    try:
+        downloader(target_dir)
+    except Exception as exc:  # pragma: no cover - defensive wrapper around third-party download errors
+        if target_dir.exists() and not _download_marker_path(model["repo_id"]).exists():
+            shutil.rmtree(target_dir, ignore_errors=True)
+        raise RuntimeError(f"Failed to download model '{model['repo_id']}': {exc}") from exc
+
+    _finalize_download(model["repo_id"])
+    return _build_model_status(model)
+
+
+def get_server_model_ids() -> tuple[str, ...]:
+    return tuple(model["id"] for model in SERVER_WHISPER_MODELS)
+
+
+def get_server_model_keys() -> set[str]:
+    keys: set[str] = set()
+    for model in SERVER_WHISPER_MODELS:
+        keys.add(model["id"])
+        keys.add(model["repo_id"])
+        keys.add(model["runtime_model_id"])
+    return keys
+
+
+def get_server_model_catalog() -> list[dict[str, Any]]:
+    return [_build_model_status(model) for model in SERVER_WHISPER_MODELS]
+
+
+def resolve_server_model_entry(model_name: str | None = None) -> dict[str, Any]:
+    selected_model = model_name or settings.whisper_model
+    for model in SERVER_WHISPER_MODELS:
+        if selected_model in {model["id"], model["repo_id"], model["runtime_model_id"]}:
+            return {**_build_model_status(model), "runtime_model_id": model["runtime_model_id"]}
+    raise ValueError(
+        f"Unsupported server transcription model '{selected_model}'. "
+        f"Choose one of: {', '.join(get_server_model_ids())}"
+    )
+
+
+def download_server_model(model_name: str) -> dict[str, Any]:
+    model = resolve_server_model_entry(model_name)
+
+    try:
+        import faster_whisper
+        from faster_whisper import utils as faster_whisper_utils
+        from faster_whisper.utils import download_model
+    except ImportError as exc:
+        raise RuntimeError(
+            "faster-whisper is not installed in this runtime. "
+            "Install it before downloading Whisper models."
+        ) from exc
+
+    supported_models = getattr(faster_whisper_utils, "_MODELS", {})
+    if isinstance(supported_models, dict) and model["runtime_model_id"] not in supported_models:
+        runtime_version = getattr(faster_whisper, "__version__", "installed")
+        raise ValueError(
+            f"Whisper model '{model['name']}' is not supported by faster-whisper {runtime_version}. "
+            f"Upgrade faster-whisper to a version that supports '{model['runtime_model_id']}' "
+            "before downloading this model."
+        )
+
+    parameters = inspect.signature(download_model).parameters
+
+    def _download(target_dir: Path) -> None:
+        if "output_dir" in parameters:
+            download_model(model["runtime_model_id"], output_dir=str(target_dir))
+            return
+        download_model(model["runtime_model_id"], str(target_dir))
+
+    return _download_with_marker(model, _download)
+
+
+def get_mlx_audio_model_ids() -> tuple[str, ...]:
+    return tuple(model["id"] for model in MLX_AUDIO_STT_MODELS)
+
+
+def get_mlx_audio_model_keys() -> set[str]:
+    keys: set[str] = set()
+    for model in MLX_AUDIO_STT_MODELS:
+        keys.add(model["id"])
+        keys.add(model["repo_id"])
+    return keys
+
+
+def get_mlx_audio_model_catalog() -> list[dict[str, Any]]:
+    return [_build_model_status(model) for model in MLX_AUDIO_STT_MODELS]
+
+
+def resolve_mlx_audio_model_entry(model_name: str | None = None) -> dict[str, Any]:
+    selected_model = model_name or settings.mlx_audio_model
+    for model in MLX_AUDIO_STT_MODELS:
+        if selected_model in {model["id"], model["repo_id"]}:
+            return _build_model_status(model)
+    raise ValueError(
+        f"Unsupported MLX Audio model '{selected_model}'. "
+        f"Choose one of: {', '.join(get_mlx_audio_model_ids())}"
+    )
+
+
+def download_mlx_audio_model(model_name: str) -> dict[str, Any]:
+    model = resolve_mlx_audio_model_entry(model_name)
+
+    try:
+        from huggingface_hub import snapshot_download
+    except ImportError as exc:
+        raise RuntimeError(
+            "huggingface_hub is not installed in this desktop runtime. "
+            "Install it in the desktop environment to download MLX models."
+        ) from exc
+
+    def _download(target_dir: Path) -> None:
+        snapshot_download(repo_id=model["repo_id"], local_dir=str(target_dir))
+
+    return _download_with_marker(model, _download)

apps/api/src/app/local_inference.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from typing import Callable
+
+import requests
+
+from app.config import settings
+
+RECOMMENDED_LOCAL_MODELS = (
+    "nvidia/parakeet-tdt-0.6b-v3",
+    "nvidia/parakeet-ctc-1.1b",
+    "mistralai/Voxtral-Mini-4B-Realtime-2602",
+    "Qwen/Qwen3-ASR-1.7B",
+)
+
+ENGINE_LABELS = {
+    "ollama": "Ollama",
+    "lmstudio": "LM Studio",
+    "llamacpp": "llama.cpp",
+}
+
+
+def _default_engine_url(engine_id: str) -> str:
+    if engine_id == "ollama":
+        return settings.ollama_base_url
+    if engine_id == "lmstudio":
+        return settings.lmstudio_base_url
+    if engine_id == "llamacpp":
+        return settings.llama_cpp_base_url
+    raise ValueError(f"Unsupported local inference engine '{engine_id}'")
+
+
+def _join_url(base_url: str, suffix: str) -> str:
+    return f"{base_url.rstrip('/')}/{suffix.lstrip('/')}"
+
+
+def _normalize_engine_url(engine_id: str, base_url: str | None = None) -> str:
+    selected = (base_url or _default_engine_url(engine_id)).strip()
+    return selected.rstrip("/")
+
+
+def _request_json(url: str) -> dict:
+    response = requests.get(url, timeout=settings.local_engine_timeout_seconds)
+    response.raise_for_status()
+    return response.json()
+
+
+def _request_ok(url: str) -> bool:
+    response = requests.get(url, timeout=settings.local_engine_timeout_seconds)
+    response.raise_for_status()
+    return True
+
+
+def _check_with_candidates(
+    engine_id: str,
+    base_url: str,
+    candidates: list[tuple[str, Callable[[dict], list[str]]]],
+    probe: Callable[[str], dict],
+) -> dict:
+    last_error = "Connection failed"
+    for suffix, parser in candidates:
+        url = _join_url(base_url, suffix)
+        try:
+            payload = probe(url)
+            return {
+                "id": engine_id,
+                "label": ENGINE_LABELS[engine_id],
+                "base_url": base_url,
+                "live": True,
+                "detail": "Connected",
+                "available_models": parser(payload),
+            }
+        except requests.RequestException as exc:
+            last_error = str(exc)
+    return {
+        "id": engine_id,
+        "label": ENGINE_LABELS[engine_id],
+        "base_url": base_url,
+        "live": False,
+        "detail": last_error,
+        "available_models": [],
+    }
+
+
+def _parse_ollama_models(payload: dict) -> list[str]:
+    return [item["name"] for item in payload.get("models", []) if item.get("name")]
+
+
+def _parse_openai_models(payload: dict) -> list[str]:
+    return [item["id"] for item in payload.get("data", []) if item.get("id")]
+
+
+def _parse_empty(_payload: dict) -> list[str]:
+    return []
+
+
+def check_engine(engine_id: str, base_url: str | None = None) -> dict:
+    normalized_url = _normalize_engine_url(engine_id, base_url)
+
+    if engine_id == "ollama":
+        return _check_with_candidates(
+            engine_id,
+            normalized_url,
+            [
+                ("api/tags", _parse_ollama_models),
+                ("v1/models", _parse_openai_models),
+            ],
+            _request_json,
+        )
+
+    if engine_id == "lmstudio":
+        return _check_with_candidates(
+            engine_id,
+            normalized_url,
+            [("models", _parse_openai_models), ("v1/models", _parse_openai_models)],
+            _request_json,
+        )
+
+    if engine_id == "llamacpp":
+        status = _check_with_candidates(
+            engine_id,
+            normalized_url,
+            [("v1/models", _parse_openai_models)],
+            _request_json,
+        )
+        if status["live"]:
+            return status
+
+        try:
+            _request_ok(_join_url(normalized_url, "health"))
+            return {
+                "id": engine_id,
+                "label": ENGINE_LABELS[engine_id],
+                "base_url": normalized_url,
+                "live": True,
+                "detail": "Connected",
+                "available_models": [],
+            }
+        except requests.RequestException as exc:
+            status["detail"] = str(exc)
+            return status
+
+    raise ValueError(f"Unsupported local inference engine '{engine_id}'")
+
+
+def get_all_engine_statuses() -> list[dict]:
+    return [check_engine(engine_id) for engine_id in ("ollama", "lmstudio", "llamacpp")]

apps/api/src/app/main.py

@@ -0,0 +1,62 @@
+from contextlib import asynccontextmanager
+import logging
+import sys
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.config import settings
+from app.db import Base, engine
+from app.middleware.logging import StructuredLoggingMiddleware
+from app.middleware.security_headers import SecurityHeadersMiddleware
+from app.routes import (
+    auth,
+    coaching,
+    curriculum,
+    dashboard,
+    health,
+    jobs,
+    news,
+    sessions,
+    settings as settings_routes,
+    setup,
+)
+from app.schema_upgrades import apply_startup_schema_upgrades
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(message)s",
+    handlers=[logging.StreamHandler(sys.stdout)],
+)
+logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    Base.metadata.create_all(bind=engine)
+    apply_startup_schema_upgrades()
+    yield
+
+
+app = FastAPI(title="Speech-Machine Tech Presenter Coach API", lifespan=lifespan)
+
+app.add_middleware(SecurityHeadersMiddleware)
+app.add_middleware(StructuredLoggingMiddleware)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origin_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(setup.router)
+app.include_router(auth.router)
+app.include_router(dashboard.router)
+app.include_router(curriculum.router)
+app.include_router(news.router)
+app.include_router(coaching.router)
+app.include_router(sessions.router)
+app.include_router(settings_routes.router)
+app.include_router(jobs.router)
+app.include_router(health.router)

apps/api/src/app/middleware/logging.py

@@ -0,0 +1,31 @@
+import json
+import logging
+import time
+from collections.abc import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+logger = logging.getLogger("speech_machine.access")
+
+
+class StructuredLoggingMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        start = time.perf_counter()
+        response = await call_next(request)
+        duration_ms = round((time.perf_counter() - start) * 1000, 2)
+        payload = {
+            "method": request.method,
+            "path": request.url.path,
+            "status": response.status_code,
+            "duration_ms": duration_ms,
+            "client_ip": request.client.host if request.client else None,
+        }
+        if response.status_code >= 500:
+            logger.error(json.dumps(payload))
+        elif response.status_code >= 400:
+            logger.warning(json.dumps(payload))
+        else:
+            logger.info(json.dumps(payload))
+        return response

apps/api/src/app/middleware/security_headers.py

@@ -0,0 +1,21 @@
+from collections.abc import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from app.config import settings
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        if settings.environment.lower() == "production":
+            response.headers["X-Frame-Options"] = "SAMEORIGIN"
+            response.headers["Permissions-Policy"] = "camera=(self), microphone=(self), geolocation=()"
+            response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
+        else:
+            response.headers["Permissions-Policy"] = "camera=*, microphone=*, geolocation=()"
+        return response

apps/api/src/app/models.py

@@ -0,0 +1,312 @@
+from datetime import date, datetime
+from sqlalchemy import Boolean, Column, Date, DateTime, Float, ForeignKey, Index, Integer, String, Text, JSON, UniqueConstraint
+from sqlalchemy.orm import relationship
+
+from app.db import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True, index=True)
+    email = Column(String(255), unique=True, index=True, nullable=False)
+    hashed_password = Column(String(255), nullable=False)
+    is_admin = Column(Boolean, default=False, nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
+    refresh_tokens = relationship(
+        "RefreshToken", back_populates="user", cascade="all, delete-orphan"
+    )
+    session_metrics = relationship("SessionMetrics", back_populates="user", cascade="all, delete-orphan")
+    daily_aggregates = relationship("DailyAggregate", back_populates="user", cascade="all, delete-orphan")
+    coaching_feedback = relationship("CoachingFeedback", back_populates="user", cascade="all, delete-orphan")
+    goals = relationship("UserGoal", back_populates="user", cascade="all, delete-orphan")
+    presenter_profile = relationship(
+        "PresenterProfile", back_populates="user", uselist=False, cascade="all, delete-orphan"
+    )
+    curriculum_completions = relationship(
+        "CurriculumDayCompletion", back_populates="user", cascade="all, delete-orphan"
+    )
+    weekly_reflections = relationship(
+        "WeeklyReflection", back_populates="user", cascade="all, delete-orphan"
+    )
+
+
+class RefreshToken(Base):
+    __tablename__ = "refresh_tokens"
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id"), nullable=False, index=True)
+    jti_hash = Column(String(64), unique=True, index=True, nullable=False)
+    expires_at = Column(DateTime, nullable=False)
+    revoked_at = Column(DateTime, nullable=True)
+    replaced_by_jti_hash = Column(String(64), nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    user = relationship("User", back_populates="refresh_tokens")
+
+
+class Session(Base):
+    __tablename__ = "sessions"
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    title = Column(String(255), nullable=True)
+    mode = Column(String(80), nullable=True)
+    prompt = Column(Text, nullable=True)
+    goal = Column(String(255), nullable=True)
+    curriculum_day = Column(Integer, nullable=True)
+    exercise_id = Column(String(100), nullable=True)
+    story_framework = Column(String(80), nullable=True)
+    target_keywords_json = Column(Text, nullable=True)
+    teleprompter_script = Column(Text, nullable=True)
+    started_at = Column(DateTime, nullable=True)
+    ended_at = Column(DateTime, nullable=True)
+    duration_ms = Column(Integer, default=0)
+    wpm_avg = Column(Float, default=0)
+    filler_count = Column(Integer, default=0)
+    eye_contact_pct = Column(Float, default=0)
+    video_path = Column(String(1024), nullable=True)
+    document_path = Column(String(1024), nullable=True)
+    document_name = Column(String(255), nullable=True)
+    document_mime_type = Column(String(255), nullable=True)
+    document_blocks_json = Column(Text, nullable=True)
+    transcription_status = Column(String(32), default="idle")
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    user = relationship("User", back_populates="sessions")
+    transcript_segments = relationship(
+        "TranscriptSegment", back_populates="session", cascade="all, delete-orphan"
+    )
+    metrics = relationship(
+        "MetricsTimeseries", back_populates="session", cascade="all, delete-orphan"
+    )
+    score = relationship("Score", back_populates="session", uselist=False, cascade="all, delete-orphan")
+    tags = relationship("Tag", back_populates="session", cascade="all, delete-orphan")
+    metrics_snapshot = relationship(
+        "SessionMetrics", back_populates="session", uselist=False, cascade="all, delete-orphan"
+    )
+    coaching_feedback = relationship(
+        "CoachingFeedback", back_populates="session", uselist=False, cascade="all, delete-orphan"
+    )
+
+
+class PresenterProfile(Base):
+    __tablename__ = "presenter_profiles"
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, unique=True, index=True)
+    display_name = Column(String(120), default="Tech Presenter", nullable=False)
+    primary_role = Column(String(120), default="Software Engineer & Tech Presenter", nullable=False)
+    focus_track = Column(String(80), default="tech_storytelling", nullable=False)
+    experience_level = Column(String(40), default="intermediate", nullable=False)
+    target_wpm_min = Column(Integer, default=125, nullable=False)
+    target_wpm_max = Column(Integer, default=155, nullable=False)
+    max_filler_rate = Column(Float, default=2.0, nullable=False)
+    min_eye_contact = Column(Float, default=0.7, nullable=False)
+    daily_minutes_goal = Column(Integer, default=15, nullable=False)
+    weaknesses = Column(JSON, nullable=True)
+    speaking_goal_statement = Column(
+        Text,
+        default="Become a confident, articulate, engaging technology presenter on camera.",
+        nullable=True,
+    )
+    curriculum_start_date = Column(Date, default=date.today, nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    user = relationship("User", back_populates="presenter_profile")
+
+
+class CurriculumDayCompletion(Base):
+    __tablename__ = "curriculum_day_completions"
+    __table_args__ = (
+        UniqueConstraint("user_id", "day_number", name="uq_curriculum_user_day"),
+        Index("ix_curriculum_user_day", "user_id", "day_number"),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    day_number = Column(Integer, nullable=False)
+    completed_session_id = Column(Integer, ForeignKey("sessions.id", ondelete="SET NULL"), nullable=True)
+    best_score = Column(Float, default=0, nullable=False)
+    attempts_count = Column(Integer, default=1, nullable=False)
+    reflection_notes = Column(Text, nullable=True)
+    completed_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    user = relationship("User", back_populates="curriculum_completions")
+
+
+class WeeklyReflection(Base):
+    __tablename__ = "weekly_reflections"
+    __table_args__ = (
+        UniqueConstraint("user_id", "week_start_date", name="uq_weekly_reflections_user_week"),
+        Index("ix_weekly_reflections_user_week", "user_id", "week_start_date"),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    week_start_date = Column(Date, nullable=False)
+    wins_note = Column(Text, nullable=True)
+    focus_next_week = Column(Text, nullable=True)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    user = relationship("User", back_populates="weekly_reflections")
+
+
+class SessionMetrics(Base):
+    __tablename__ = "session_metrics"
+    __table_args__ = (
+        Index("ix_session_metrics_user_date", "user_id", "recorded_at"),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    session_id = Column(Integer, ForeignKey("sessions.id", ondelete="CASCADE"), nullable=False, unique=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    recorded_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+
+    duration_seconds = Column(Float, default=0, nullable=False)
+    word_count = Column(Integer, default=0, nullable=False)
+    wpm = Column(Float, default=0, nullable=False)
+    filler_count = Column(Integer, default=0, nullable=False)
+    filler_rate = Column(Float, default=0, nullable=False)
+    pause_count = Column(Integer, default=0, nullable=False)
+    unique_word_count = Column(Integer, default=0, nullable=False)
+    vocabulary_density = Column(Float, default=0, nullable=False)
+
+    eye_contact_score = Column(Float, nullable=True)
+    smile_score = Column(Float, nullable=True)
+    head_stability_score = Column(Float, nullable=True)
+    loudness_score = Column(Float, nullable=True)
+
+    speech_score = Column(Float, default=0, nullable=False)
+    delivery_score = Column(Float, default=0, nullable=False)
+    overall_score = Column(Float, default=0, nullable=False)
+    filler_breakdown = Column(JSON, nullable=True)
+    wpm_timeline = Column(JSON, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    session = relationship("Session", back_populates="metrics_snapshot")
+    user = relationship("User", back_populates="session_metrics")
+
+
+class DailyAggregate(Base):
+    __tablename__ = "daily_aggregates"
+    __table_args__ = (
+        UniqueConstraint("user_id", "practice_date", name="uq_daily_aggregates_user_date"),
+        Index("ix_daily_aggregates_user_date", "user_id", "practice_date"),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    practice_date = Column(Date, nullable=False)
+    session_count = Column(Integer, default=0, nullable=False)
+    total_duration_seconds = Column(Float, default=0, nullable=False)
+    avg_wpm = Column(Float, default=0, nullable=False)
+    avg_filler_rate = Column(Float, default=0, nullable=False)
+    avg_overall_score = Column(Float, default=0, nullable=False)
+    avg_speech_score = Column(Float, default=0, nullable=False)
+    avg_delivery_score = Column(Float, default=0, nullable=False)
+    best_overall_score = Column(Float, default=0, nullable=False)
+
+    user = relationship("User", back_populates="daily_aggregates")
+
+
+class CoachingFeedback(Base):
+    __tablename__ = "coaching_feedback"
+    __table_args__ = (
+        Index("ix_coaching_feedback_user_created", "user_id", "created_at"),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    session_id = Column(Integer, ForeignKey("sessions.id", ondelete="CASCADE"), nullable=False, unique=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    status = Column(String(20), default="pending", nullable=False)
+    model_used = Column(String(100), nullable=True)
+    generation_time_ms = Column(Integer, nullable=True)
+    summary = Column(Text, nullable=True)
+    strengths = Column(JSON, nullable=True)
+    improvements = Column(JSON, nullable=True)
+    drills = Column(JSON, nullable=True)
+    practice_plan = Column(JSON, nullable=True)
+    raw_response = Column(Text, nullable=True)
+    compared_to_session_id = Column(Integer, nullable=True)
+    trend_context = Column(JSON, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    error_message = Column(Text, nullable=True)
+
+    session = relationship("Session", back_populates="coaching_feedback")
+    user = relationship("User", back_populates="coaching_feedback")
+
+
+class UserGoal(Base):
+    __tablename__ = "user_goals"
+    __table_args__ = (
+        UniqueConstraint("user_id", "metric_name", name="uq_user_goals_user_metric"),
+        Index("ix_user_goals_user_active", "user_id", "is_active"),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    metric_name = Column(String(50), nullable=False)
+    comparison = Column(String(10), nullable=False)
+    target_value = Column(Float, nullable=False)
+    target_upper = Column(Float, nullable=True)
+    is_active = Column(Boolean, default=True, nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    user = relationship("User", back_populates="goals")
+
+
+class TranscriptSegment(Base):
+    __tablename__ = "transcript_segments"
+
+    id = Column(Integer, primary_key=True, index=True)
+    session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False)
+    start_ms = Column(Integer, nullable=False)
+    end_ms = Column(Integer, nullable=False)
+    text = Column(Text, nullable=False)
+
+    session = relationship("Session", back_populates="transcript_segments")
+
+
+class MetricsTimeseries(Base):
+    __tablename__ = "metrics_timeseries"
+
+    id = Column(Integer, primary_key=True, index=True)
+    session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False)
+    t = Column(Integer, nullable=False)
+    wpm = Column(Float, default=0)
+    rms = Column(Float, default=0)
+    eye_contact = Column(Float, default=0)
+    smile = Column(Float, default=0)
+    yaw = Column(Float, default=0)
+    pitch = Column(Float, default=0)
+    roll = Column(Float, default=0)
+    filler_count = Column(Integer, default=0)
+    pause_ms = Column(Integer, default=0)
+
+    session = relationship("Session", back_populates="metrics")
+
+
+class Score(Base):
+    __tablename__ = "scores"
+
+    id = Column(Integer, primary_key=True, index=True)
+    session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False, unique=True)
+    data = Column(JSON, nullable=False)
+
+    session = relationship("Session", back_populates="score")
+
+
+class Tag(Base):
+    __tablename__ = "tags"
+
+    id = Column(Integer, primary_key=True, index=True)
+    session_id = Column(Integer, ForeignKey("sessions.id"), nullable=False)
+    name = Column(String(80), nullable=False)
+
+    session = relationship("Session", back_populates="tags")

apps/api/src/app/rate_limit.py

@@ -0,0 +1,27 @@
+import time
+from collections import defaultdict, deque
+from collections.abc import Callable
+
+from fastapi import HTTPException, Request, status
+
+WINDOW_SECONDS = 60
+_hits: dict[str, deque[float]] = defaultdict(deque)
+
+
+def rate_limit(limit: int) -> Callable:
+    def dependency(request: Request) -> None:
+        client = request.client.host if request.client else "unknown"
+        key = f"{client}:{request.url.path}"
+        now = time.time()
+        window_start = now - WINDOW_SECONDS
+        bucket = _hits[key]
+        while bucket and bucket[0] < window_start:
+            bucket.popleft()
+        if len(bucket) >= limit:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded. Try again shortly.",
+            )
+        bucket.append(now)
+
+    return dependency

apps/api/src/app/routes/__init__.py

@@ -0,0 +1,3 @@
+from app.routes import auth, sessions, settings
+
+__all__ = ["auth", "sessions", "settings"]

apps/api/src/app/routes/auth.py

@@ -0,0 +1,63 @@
+from fastapi import APIRouter, Depends, HTTPException, Response, status
+from sqlalchemy.orm import Session
+
+from app import models, schemas
+from app.auth import (
+    authenticate_user,
+    get_current_user,
+    get_refresh_cookie,
+    hash_password,
+    issue_token_pair,
+    revoke_refresh_token,
+    rotate_refresh_token,
+)
+from app.db import get_db
+from app.rate_limit import rate_limit
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+@router.post("/signup", response_model=schemas.Token)
+def signup(payload: schemas.UserCreate, response: Response, db: Session = Depends(get_db)):
+    if db.query(models.User.id).first() is None:
+        raise HTTPException(status_code=409, detail="Initial setup required")
+    existing = db.query(models.User).filter(models.User.email == payload.email).first()
+    if existing:
+        raise HTTPException(status_code=400, detail="Email already registered")
+    user = models.User(email=payload.email, hashed_password=hash_password(payload.password), is_admin=False)
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+    return issue_token_pair(db, response, user)
+
+
+@router.post("/login", response_model=schemas.Token, dependencies=[Depends(rate_limit(10))])
+def login(payload: schemas.UserLogin, response: Response, db: Session = Depends(get_db)):
+    user = authenticate_user(db, payload.email, payload.password)
+    if not user:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid email or password")
+    return issue_token_pair(db, response, user)
+
+
+@router.post("/refresh", response_model=schemas.Token)
+def refresh(
+    response: Response,
+    refresh_token: str | None = Depends(get_refresh_cookie),
+    db: Session = Depends(get_db),
+):
+    return rotate_refresh_token(db, response, refresh_token)
+
+
+@router.get("/me", response_model=schemas.UserOut)
+def me(current_user: models.User = Depends(get_current_user)):
+    return current_user
+
+
+@router.post("/logout")
+def logout(
+    response: Response,
+    refresh_token: str | None = Depends(get_refresh_cookie),
+    db: Session = Depends(get_db),
+):
+    revoke_refresh_token(db, response, refresh_token)
+    return {"status": "ok"}

apps/api/src/app/routes/coaching.py

@@ -0,0 +1,188 @@
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+
+from app import models
+from app.auth import get_current_user
+from app.db import get_db
+from app.services.analytics import compute_session_metrics, get_active_goal_context, get_session_history
+from app.services.coaching import generate_coaching_feedback
+from app.worker.enqueue import enqueue_coaching
+from app.worker.jobs import _snapshot_to_dict, _transcript_text
+
+router = APIRouter(prefix="/coaching", tags=["coaching"])
+
+
+def _generate_inline_coaching(db: Session, session: models.Session, user_id: int) -> models.CoachingFeedback:
+    feedback = (
+        db.query(models.CoachingFeedback)
+        .filter(models.CoachingFeedback.session_id == session.id)
+        .first()
+    )
+    if feedback is None:
+        feedback = models.CoachingFeedback(session_id=session.id, user_id=user_id, status="generating")
+        db.add(feedback)
+        db.commit()
+        db.refresh(feedback)
+
+    snapshot = compute_session_metrics(db, session.id)
+    metrics = _snapshot_to_dict(snapshot, session)
+    transcript = _transcript_text(session)
+    history = get_session_history(db, user_id, limit=10)
+    active_goals = get_active_goal_context(db, user_id)
+
+    try:
+        result = generate_coaching_feedback(transcript, metrics, history, None, active_goals)
+        feedback.status = "completed"
+        feedback.summary = result["summary"]
+        feedback.strengths = result["strengths"]
+        feedback.improvements = result["improvements"]
+        feedback.drills = result["drills"]
+        feedback.practice_plan = result["practice_plan"]
+        feedback.raw_response = result["raw_response"]
+        feedback.model_used = result["model_used"]
+        feedback.generation_time_ms = result["generation_time_ms"]
+        feedback.error_message = None
+        feedback.trend_context = {
+            "sessions_analyzed": len(history),
+            "progress_note": result.get("progress_note", ""),
+        }
+    except Exception as exc:
+        feedback.status = "failed"
+        feedback.error_message = str(exc)[:1000]
+
+    db.commit()
+    db.refresh(feedback)
+    return feedback
+
+
+@router.get("/session/{session_id}")
+def get_session_coaching(
+    session_id: int,
+    auto: bool = Query(default=False),
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    feedback = (
+        db.query(models.CoachingFeedback)
+        .filter(
+            models.CoachingFeedback.session_id == session_id,
+            models.CoachingFeedback.user_id == current_user.id,
+        )
+        .first()
+    )
+    if feedback is None and auto:
+        session = (
+            db.query(models.Session)
+            .filter(models.Session.id == session_id, models.Session.user_id == current_user.id)
+            .first()
+        )
+        if session is not None and (session.transcript_segments or session.duration_ms > 0):
+            feedback = _generate_inline_coaching(db, session, current_user.id)
+
+    if feedback is None:
+        return {"status": "not_available"}
+    return _serialize_feedback(feedback)
+
+
+@router.get("/latest")
+def latest_coaching(
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    feedback = (
+        db.query(models.CoachingFeedback)
+        .filter(
+            models.CoachingFeedback.user_id == current_user.id,
+            models.CoachingFeedback.status == "completed",
+        )
+        .order_by(models.CoachingFeedback.created_at.desc())
+        .first()
+    )
+    if feedback is None:
+        return {"status": "not_available"}
+    return _serialize_feedback(feedback)
+
+
+@router.get("/history")
+def coaching_history(
+    limit: int = Query(default=10, ge=1, le=50),
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    rows = (
+        db.query(models.CoachingFeedback)
+        .filter(
+            models.CoachingFeedback.user_id == current_user.id,
+            models.CoachingFeedback.status == "completed",
+        )
+        .order_by(models.CoachingFeedback.created_at.desc())
+        .limit(limit)
+        .all()
+    )
+    return [_serialize_feedback(row, include_raw=False) for row in rows]
+
+
+@router.post("/session/{session_id}/retry")
+async def retry_session_coaching(
+    session_id: int,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = (
+        db.query(models.Session)
+        .filter(models.Session.id == session_id, models.Session.user_id == current_user.id)
+        .first()
+    )
+    if session is None:
+        raise HTTPException(status_code=404, detail="Session not found")
+
+    feedback = (
+        db.query(models.CoachingFeedback)
+        .filter(models.CoachingFeedback.session_id == session_id)
+        .first()
+    )
+    if feedback is None:
+        feedback = models.CoachingFeedback(
+            session_id=session_id,
+            user_id=current_user.id,
+            status="pending",
+        )
+        db.add(feedback)
+    feedback.user_id = current_user.id
+    feedback.status = "pending"
+    feedback.error_message = None
+    feedback.trend_context = None
+    db.commit()
+
+    try:
+        job_id = await enqueue_coaching(session_id, current_user.id)
+    except Exception as exc:
+        feedback.status = "failed"
+        feedback.error_message = "Job backend unavailable"
+        db.commit()
+        raise HTTPException(status_code=503, detail="Job backend unavailable") from exc
+
+    feedback.trend_context = {"job_id": job_id}
+    db.commit()
+    return {"status": "queued", "job_id": job_id}
+
+
+def _serialize_feedback(feedback: models.CoachingFeedback, include_raw: bool = False) -> dict:
+    payload = {
+        "id": feedback.id,
+        "session_id": feedback.session_id,
+        "status": feedback.status,
+        "summary": feedback.summary,
+        "strengths": feedback.strengths or [],
+        "improvements": feedback.improvements or [],
+        "drills": feedback.drills or [],
+        "practice_plan": feedback.practice_plan or {},
+        "trend_context": feedback.trend_context or {},
+        "model_used": feedback.model_used,
+        "generation_time_ms": feedback.generation_time_ms,
+        "created_at": feedback.created_at.isoformat() if feedback.created_at else None,
+        "error_message": feedback.error_message if feedback.status == "failed" else None,
+    }
+    if include_raw:
+        payload["raw_response"] = feedback.raw_response
+    return payload

apps/api/src/app/routes/curriculum.py

@@ -0,0 +1,112 @@
+from datetime import date
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+
+from app import models, schemas
+from app.auth import get_current_user
+from app.db import get_db
+from app.services.analytics import prepare_user_analytics
+from app.services.curriculum import (
+    get_curriculum_plan,
+    get_or_create_profile,
+    get_personalized_exercises,
+    record_curriculum_completion,
+    serialize_profile,
+)
+
+router = APIRouter(prefix="/curriculum", tags=["curriculum"])
+
+
+@router.get("/profile")
+def read_presenter_profile(
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    profile = get_or_create_profile(db, current_user.id)
+    return serialize_profile(profile)
+
+
+@router.put("/profile")
+def update_presenter_profile(
+    payload: schemas.PresenterProfileUpdate,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    profile = get_or_create_profile(db, current_user.id)
+    updates = payload.model_dump(exclude_unset=True)
+    reset_start = updates.pop("reset_start_date", False)
+
+    wpm_min = updates.get("target_wpm_min", profile.target_wpm_min)
+    wpm_max = updates.get("target_wpm_max", profile.target_wpm_max)
+    if wpm_max <= wpm_min:
+        raise HTTPException(status_code=422, detail="target_wpm_max must be greater than target_wpm_min")
+
+    for key, value in updates.items():
+        if value is not None:
+            setattr(profile, key, value)
+    if reset_start:
+        profile.curriculum_start_date = date.today()
+
+    db.commit()
+    db.refresh(profile)
+    return serialize_profile(profile)
+
+
+@router.get("/plan")
+def read_curriculum_plan(
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    prepare_user_analytics(db, current_user.id)
+    return get_curriculum_plan(db, current_user.id)
+
+
+@router.post("/days/{day_number}/complete")
+def complete_curriculum_day(
+    day_number: int,
+    payload: schemas.CurriculumCompleteRequest,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    if day_number < 1 or day_number > 30:
+        raise HTTPException(status_code=422, detail="Day number must be between 1 and 30")
+
+    score_value = payload.score
+    if payload.session_id is not None:
+        linked_session = (
+            db.query(models.Session)
+            .filter(models.Session.id == payload.session_id, models.Session.user_id == current_user.id)
+            .first()
+        )
+        if linked_session is None:
+            raise HTTPException(status_code=404, detail="Linked session not found")
+        if score_value is None and linked_session.score and isinstance(linked_session.score.data, dict):
+            score_value = float(linked_session.score.data.get("total", 0) or 0)
+
+    row = record_curriculum_completion(
+        db=db,
+        user_id=current_user.id,
+        day_number=day_number,
+        session_id=payload.session_id,
+        score=score_value,
+        reflection_notes=payload.reflection_notes,
+    )
+    return {
+        "day_number": row.day_number,
+        "completed": True,
+        "completed_session_id": row.completed_session_id,
+        "best_score": row.best_score,
+        "attempts_count": row.attempts_count,
+        "reflection_notes": row.reflection_notes,
+        "completed_at": row.completed_at.isoformat() if row.completed_at else None,
+    }
+
+
+@router.get("/exercises")
+def read_exercises(
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    prepare_user_analytics(db, current_user.id)
+    return get_personalized_exercises(db, current_user.id)

apps/api/src/app/routes/dashboard.py

@@ -0,0 +1,203 @@
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+
+from app import models, schemas
+from app.auth import get_current_user
+from app.db import get_db
+from app.services.analytics import (
+    compare_sessions,
+    get_activity_heatmap,
+    get_filler_breakdown,
+    get_goal_current_values,
+    get_overview_stats,
+    get_session_history,
+    get_trend_data,
+    get_user_goals,
+    get_weekly_review,
+    prepare_user_analytics,
+    save_weekly_reflection,
+    serialize_goal,
+)
+
+router = APIRouter(prefix="/dashboard", tags=["dashboard"])
+
+
+def _validate_goal_values(comparison: str, target_value: float, target_upper: float | None) -> None:
+    if comparison == "between" and (target_upper is None or target_upper <= target_value):
+        raise HTTPException(status_code=422, detail="between goals require target_upper greater than target_value")
+    if comparison != "between" and target_upper is not None:
+        raise HTTPException(status_code=422, detail="target_upper is only valid for between goals")
+
+
+@router.get("/overview")
+def overview(
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    prepare_user_analytics(db, current_user.id)
+    return get_overview_stats(db, current_user.id)
+
+
+@router.get("/weekly-review")
+def weekly_review(
+    weeks_ago: int = Query(default=0, ge=0, le=12),
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    prepare_user_analytics(db, current_user.id)
+    return get_weekly_review(db, current_user.id, weeks_ago=weeks_ago)
+
+
+@router.put("/weekly-review/note")
+def update_weekly_note(
+    payload: schemas.WeeklyNoteUpdate,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    return save_weekly_reflection(
+        db,
+        current_user.id,
+        payload.week_start_date,
+        payload.wins_note,
+        payload.focus_next_week,
+    )
+
+
+@router.get("/goals", response_model=list[schemas.UserGoalOut])
+def goals(
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    prepare_user_analytics(db, current_user.id)
+    return get_user_goals(db, current_user.id)
+
+
+@router.post("/goals", response_model=schemas.UserGoalOut, status_code=201)
+def create_goal(
+    payload: schemas.UserGoalCreate,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    existing = (
+        db.query(models.UserGoal)
+        .filter(
+            models.UserGoal.user_id == current_user.id,
+            models.UserGoal.metric_name == payload.metric_name,
+        )
+        .first()
+    )
+    if existing is not None:
+        raise HTTPException(status_code=409, detail="A goal for this metric already exists")
+    goal = models.UserGoal(user_id=current_user.id, **payload.model_dump())
+    db.add(goal)
+    db.commit()
+    db.refresh(goal)
+    current = get_goal_current_values(db, current_user.id).get(goal.metric_name)
+    return serialize_goal(goal, current)
+
+
+@router.patch("/goals/{goal_id}", response_model=schemas.UserGoalOut)
+def update_goal(
+    goal_id: int,
+    payload: schemas.UserGoalUpdate,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    goal = (
+        db.query(models.UserGoal)
+        .filter(models.UserGoal.id == goal_id, models.UserGoal.user_id == current_user.id)
+        .first()
+    )
+    if goal is None:
+        raise HTTPException(status_code=404, detail="Goal not found")
+    updates = payload.model_dump(exclude_unset=True)
+    comparison = updates.get("comparison", goal.comparison)
+    target_value = updates.get("target_value", goal.target_value)
+    target_upper = updates.get("target_upper", goal.target_upper)
+    if comparison != "between" and "comparison" in updates and "target_upper" not in updates:
+        target_upper = None
+        updates["target_upper"] = None
+    _validate_goal_values(comparison, target_value, target_upper)
+    for key, value in updates.items():
+        setattr(goal, key, value)
+    db.commit()
+    db.refresh(goal)
+    current = get_goal_current_values(db, current_user.id).get(goal.metric_name)
+    return serialize_goal(goal, current)
+
+
+@router.delete("/goals/{goal_id}")
+def delete_goal(
+    goal_id: int,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    goal = (
+        db.query(models.UserGoal)
+        .filter(models.UserGoal.id == goal_id, models.UserGoal.user_id == current_user.id)
+        .first()
+    )
+    if goal is None:
+        raise HTTPException(status_code=404, detail="Goal not found")
+    db.delete(goal)
+    db.commit()
+    return {"status": "deleted"}
+
+
+@router.get("/trends/{metric}")
+def trends(
+    metric: str,
+    days: int = Query(default=90, ge=7, le=365),
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    prepare_user_analytics(db, current_user.id)
+    try:
+        return get_trend_data(db, current_user.id, metric, days)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@router.get("/sessions")
+def sessions(
+    limit: int = Query(default=20, ge=1, le=100),
+    offset: int = Query(default=0, ge=0),
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    prepare_user_analytics(db, current_user.id)
+    return get_session_history(db, current_user.id, limit, offset)
+
+
+@router.get("/heatmap")
+def heatmap(
+    days: int = Query(default=365, ge=30, le=365),
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    prepare_user_analytics(db, current_user.id)
+    return get_activity_heatmap(db, current_user.id, days)
+
+
+@router.get("/fillers")
+def fillers(
+    last_n: int = Query(default=20, ge=5, le=100),
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    prepare_user_analytics(db, current_user.id)
+    return get_filler_breakdown(db, current_user.id, last_n)
+
+
+@router.get("/compare")
+def compare(
+    session_a: int = Query(...),
+    session_b: int = Query(...),
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    prepare_user_analytics(db, current_user.id)
+    try:
+        return compare_sessions(db, current_user.id, session_a, session_b)
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc

apps/api/src/app/routes/health.py

@@ -0,0 +1,37 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy import text
+from sqlalchemy.orm import Session
+
+from app.config import settings
+from app.db import get_db
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health")
+def health():
+    return {"status": "ok"}
+
+
+@router.get("/health/ready")
+def readiness(db: Session = Depends(get_db)):
+    checks: dict[str, str] = {}
+    try:
+        db.execute(text("SELECT 1"))
+        checks["database"] = "ok"
+    except Exception as exc:
+        checks["database"] = f"error: {type(exc).__name__}"
+
+    try:
+        import redis
+
+        client = redis.Redis(host=settings.redis_host, port=settings.redis_port, socket_connect_timeout=1)
+        client.ping()
+        checks["redis"] = "ok"
+    except Exception as exc:
+        checks["redis"] = f"error: {type(exc).__name__}"
+
+    return {
+        "status": "ok" if all(value == "ok" for value in checks.values()) else "degraded",
+        "checks": checks,
+    }

apps/api/src/app/routes/jobs.py

@@ -0,0 +1,14 @@
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.auth import get_current_user
+from app.worker.enqueue import get_job_status
+
+router = APIRouter(prefix="/jobs", tags=["jobs"])
+
+
+@router.get("/{job_id}")
+async def job_status(job_id: str, _user=Depends(get_current_user)):
+    try:
+        return await get_job_status(job_id)
+    except Exception as exc:
+        raise HTTPException(status_code=503, detail="Job backend unavailable") from exc

apps/api/src/app/routes/news.py

@@ -0,0 +1,32 @@
+from fastapi import APIRouter, Depends, Query
+
+from app import models, schemas
+from app.auth import get_current_user
+from app.services.tech_news import build_storyboard, fetch_tech_news_feed
+
+router = APIRouter(prefix="/news", tags=["news"])
+
+
+@router.get("/feed")
+def get_news_feed(
+    category: str | None = Query(default=None),
+    refresh: bool = Query(default=False),
+    _current_user: models.User = Depends(get_current_user),
+):
+    return fetch_tech_news_feed(category=category, force_refresh=refresh)
+
+
+@router.post("/storyboard")
+def create_storyboard(
+    payload: schemas.StoryboardRequest,
+    _current_user: models.User = Depends(get_current_user),
+):
+    return build_storyboard(
+        headline=payload.headline,
+        summary=payload.summary,
+        source=payload.source,
+        url=payload.url,
+        category=payload.category,
+        framework=payload.framework,
+        personal_angle=payload.personal_angle,
+    )

apps/api/src/app/routes/sessions.py

@@ -0,0 +1,987 @@
+import json
+import os
+import re
+import shutil
+import tempfile
+import textwrap
+import zipfile
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+from fastapi.responses import FileResponse, Response
+from sqlalchemy.orm import Session
+
+from app import models, schemas, transcription
+from app.auth import get_current_user
+from app.config import settings
+from app.db import SessionLocal, get_db
+from app.scoring import compute_score, compute_wpm, count_fillers, count_words
+from app.services.analytics import compute_session_metrics
+from app.services.curriculum import record_curriculum_completion
+from app.storage import storage_client
+from app.worker.enqueue import enqueue_transcription
+
+router = APIRouter(prefix="/sessions", tags=["sessions"])
+
+
+def _resolve_video_format(value: Optional[str]) -> tuple[str, str]:
+    if not value:
+        return "webm", "video/webm"
+    lower = value.lower()
+    if "audio/" in lower:
+        if "wav" in lower:
+            return "wav", "audio/wav"
+        if "mp4" in lower or "m4a" in lower or "aac" in lower:
+            return "mp4", "audio/mp4"
+        return "webm", "audio/webm"
+    if "video/" in lower:
+        if "mp4" in lower:
+            return "mp4", "video/mp4"
+        if "quicktime" in lower:
+            return "mp4", "video/quicktime"
+        if "webm" in lower:
+            return "webm", "video/webm"
+        return "webm", "video/webm"
+    suffix = Path(lower).suffix
+    if suffix == ".mp4":
+        return "mp4", "video/mp4"
+    if suffix == ".m4a":
+        return "mp4", "audio/mp4"
+    if suffix == ".wav":
+        return "wav", "audio/wav"
+    if suffix == ".mov":
+        return "mp4", "video/quicktime"
+    if suffix == ".webm":
+        return "webm", "video/webm"
+    return "webm", "video/webm"
+
+
+def _detect_media_type(video_path: str, fallback: str) -> str:
+    try:
+        with open(video_path, "rb") as video_file:
+            header = video_file.read(16)
+        if len(header) >= 8 and header[4:8] == b"ftyp":
+            return "audio/mp4" if fallback.startswith("audio/") else "video/mp4"
+        if header.startswith(b"\x1a\x45\xdf\xa3"):
+            return "audio/webm" if fallback.startswith("audio/") else "video/webm"
+        if len(header) >= 12 and header[:4] == b"RIFF" and header[8:12] == b"WAVE":
+            return "audio/wav"
+    except OSError:
+        return fallback
+    return fallback
+
+
+def _file_size_and_header(file_obj, header_size: int = 16) -> tuple[int, bytes]:
+    current = file_obj.tell()
+    file_obj.seek(0, os.SEEK_END)
+    size = file_obj.tell()
+    file_obj.seek(0)
+    header = file_obj.read(header_size)
+    file_obj.seek(current)
+    return size, header
+
+
+def _validate_size(size: int, label: str) -> None:
+    if size > settings.max_upload_bytes:
+        raise HTTPException(
+            status_code=413,
+            detail=f"{label} exceeds the {settings.max_upload_mb} MB upload limit.",
+        )
+
+
+def _validate_video_header(header: bytes, media_type: str) -> None:
+    if media_type in {"video/mp4", "video/quicktime", "audio/mp4"}:
+        if len(header) >= 8 and header[4:8] == b"ftyp":
+            return
+    if media_type in {"video/webm", "audio/webm"} and header.startswith(b"\x1a\x45\xdf\xa3"):
+        return
+    if media_type == "audio/wav" and len(header) >= 12 and header[:4] == b"RIFF" and header[8:12] == b"WAVE":
+        return
+    raise HTTPException(status_code=415, detail="Unsupported or invalid video file.")
+
+
+def _validate_video_upload(file: UploadFile, media_type: str) -> None:
+    size, header = _file_size_and_header(file.file)
+    _validate_size(size, "Video")
+    _validate_video_header(header, media_type)
+    file.file.seek(0)
+
+
+def _validate_video_path(path: Path, media_type: str) -> None:
+    size = path.stat().st_size
+    _validate_size(size, "Video")
+    with open(path, "rb") as merged:
+        header = merged.read(16)
+    _validate_video_header(header, media_type)
+
+
+def _validate_document_upload(file: UploadFile, extension: str, mime_type: str) -> None:
+    size, header = _file_size_and_header(file.file)
+    _validate_size(size, "Document")
+    if extension == ".pdf" and not header.startswith(b"%PDF-"):
+        raise HTTPException(status_code=415, detail="Invalid PDF file.")
+    if mime_type == "text/plain" and b"\x00" in header:
+        raise HTTPException(status_code=415, detail="Invalid text file.")
+    file.file.seek(0)
+
+
+def _serialize_transcript_segments(
+    transcript_segments: list[models.TranscriptSegment],
+) -> list[schemas.TranscriptSegmentOut]:
+    return [
+        schemas.TranscriptSegmentOut(
+            id=segment.id,
+            start_ms=segment.start_ms,
+            end_ms=segment.end_ms,
+            text=segment.text,
+        )
+        for segment in transcript_segments
+    ]
+
+
+def _deserialize_document_blocks(raw_value: str | None) -> list[schemas.DocumentBlockOut]:
+    if not raw_value:
+        return []
+    try:
+        payload = json.loads(raw_value)
+    except json.JSONDecodeError:
+        return []
+
+    if not isinstance(payload, list):
+        return []
+
+    blocks: list[schemas.DocumentBlockOut] = []
+    for index, item in enumerate(payload):
+        text = item.get("text") if isinstance(item, dict) else item if isinstance(item, str) else ""
+        if not isinstance(text, str) or not text.strip():
+            continue
+        blocks.append(schemas.DocumentBlockOut(index=index, text=text.strip()))
+    return blocks
+
+
+def _serialize_document(session: models.Session) -> schemas.SessionDocumentOut | None:
+    blocks = _deserialize_document_blocks(session.document_blocks_json)
+    if not session.document_name or not session.document_mime_type or not blocks:
+        return None
+    return schemas.SessionDocumentOut(
+        name=session.document_name,
+        mime_type=session.document_mime_type,
+        blocks=blocks,
+    )
+
+
+def _serialize_metrics(metrics: list[models.MetricsTimeseries]) -> list[schemas.MetricsPointCreate]:
+    return [
+        schemas.MetricsPointCreate(
+            t=point.t,
+            wpm=point.wpm,
+            rms=point.rms,
+            eye_contact=point.eye_contact,
+            smile=point.smile,
+            yaw=point.yaw,
+            pitch=point.pitch,
+            roll=point.roll,
+            filler_count=point.filler_count,
+            pause_ms=point.pause_ms,
+        )
+        for point in metrics
+    ]
+
+
+def _parse_keywords(raw: str | None) -> list[str]:
+    if not raw:
+        return []
+    try:
+        parsed = json.loads(raw)
+        if isinstance(parsed, list):
+            return [str(k) for k in parsed if str(k).strip()]
+    except json.JSONDecodeError:
+        pass
+    return []
+
+
+def _safe_filename(value: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", value).strip("_")
+    return cleaned or "session"
+
+
+def _session_transcript_filename(session: models.Session, extension: str) -> str:
+    title = session.title or session.mode or f"session_{session.id}"
+    return f"{_safe_filename(title)}_transcript.{extension}"
+
+
+def _format_timestamp(ms: int) -> str:
+    total_seconds = max(ms, 0) // 1000
+    minutes, seconds = divmod(total_seconds, 60)
+    hours, minutes = divmod(minutes, 60)
+    if hours:
+        return f"{hours:02d}:{minutes:02d}:{seconds:02d}"
+    return f"{minutes:02d}:{seconds:02d}"
+
+
+def _build_transcript_text(session: models.Session) -> str:
+    lines = [
+        session.title or session.mode or f"Session {session.id}",
+        f"Duration: {_format_timestamp(session.duration_ms)}",
+        "",
+    ]
+    for segment in session.transcript_segments:
+        lines.append(f"[{_format_timestamp(segment.start_ms)}] {segment.text}")
+    return "\n".join(lines).strip() + "\n"
+
+
+def _escape_pdf_text(text: str) -> str:
+    return text.replace("\\", "\\\\").replace("(", "\\(").replace(")", "\\)")
+
+
+def _pdf_stream(lines: list[str]) -> bytes:
+    commands = ["BT", "/F1 11 Tf", "14 TL", "72 770 Td"]
+    first_line = True
+    for line in lines:
+        wrapped_lines = textwrap.wrap(
+            line,
+            width=88,
+            replace_whitespace=False,
+            drop_whitespace=False,
+        ) or [""]
+        for wrapped in wrapped_lines:
+            if first_line:
+                commands.append(f"({_escape_pdf_text(wrapped)}) Tj")
+                first_line = False
+            else:
+                commands.append("T*")
+                commands.append(f"({_escape_pdf_text(wrapped)}) Tj")
+    commands.append("ET")
+    return "\n".join(commands).encode("latin-1", errors="replace")
+
+
+def _build_transcript_pdf(session: models.Session) -> bytes:
+    transcript_lines = _build_transcript_text(session).splitlines()
+    lines_per_page = 48
+    pages = [
+        transcript_lines[index:index + lines_per_page]
+        for index in range(0, len(transcript_lines), lines_per_page)
+    ] or [["Transcript unavailable."]]
+
+    objects: list[bytes] = []
+    page_object_numbers: list[int] = []
+    current_object = 4
+
+    for page_lines in pages:
+        page_object_numbers.append(current_object)
+        current_object += 2
+
+    objects.append(b"<< /Type /Catalog /Pages 2 0 R >>")
+    kids = " ".join(f"{number} 0 R" for number in page_object_numbers)
+    objects.append(f"<< /Type /Pages /Kids [{kids}] /Count {len(page_object_numbers)} >>".encode("latin-1"))
+    objects.append(b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>")
+
+    for index, page_lines in enumerate(pages):
+        page_object_number = page_object_numbers[index]
+        content_object_number = page_object_number + 1
+        objects.append(
+            (
+                f"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] "
+                f"/Resources << /Font << /F1 3 0 R >> >> /Contents {content_object_number} 0 R >>"
+            ).encode("latin-1")
+        )
+        content_bytes = _pdf_stream(page_lines)
+        objects.append(
+            b"<< /Length "
+            + str(len(content_bytes)).encode("latin-1")
+            + b" >>\nstream\n"
+            + content_bytes
+            + b"\nendstream"
+        )
+
+    pdf = bytearray(b"%PDF-1.4\n%\xe2\xe3\xcf\xd3\n")
+    offsets = [0]
+    for object_number, body in enumerate(objects, start=1):
+        offsets.append(len(pdf))
+        pdf.extend(f"{object_number} 0 obj\n".encode("latin-1"))
+        pdf.extend(body)
+        pdf.extend(b"\nendobj\n")
+
+    xref_offset = len(pdf)
+    pdf.extend(f"xref\n0 {len(objects) + 1}\n".encode("latin-1"))
+    pdf.extend(b"0000000000 65535 f \n")
+    for offset in offsets[1:]:
+        pdf.extend(f"{offset:010d} 00000 n \n".encode("latin-1"))
+    pdf.extend(
+        (
+            f"trailer\n<< /Size {len(objects) + 1} /Root 1 0 R >>\n"
+            f"startxref\n{xref_offset}\n%%EOF\n"
+        ).encode("latin-1")
+    )
+    return bytes(pdf)
+
+
+def _raise_if_transcript_missing(session: models.Session) -> None:
+    if not session.transcript_segments:
+        raise HTTPException(status_code=400, detail="Transcript not available yet")
+
+
+def _status_for_missing_video(session: models.Session) -> str:
+    if session.transcript_segments:
+        return "complete"
+    return "idle"
+
+
+def _resolve_document_format(filename: str | None, content_type: str | None) -> tuple[str, str]:
+    suffix = Path(filename or "").suffix.lower()
+    normalized_content_type = (content_type or "").split(";")[0].strip().lower()
+    if suffix == ".pdf" or normalized_content_type == "application/pdf":
+        return ".pdf", "application/pdf"
+    if suffix == ".txt" or normalized_content_type == "text/plain":
+        return ".txt", "text/plain"
+    raise HTTPException(status_code=400, detail="Unsupported document type. Upload a PDF or TXT file.")
+
+
+def _normalize_document_blocks_payload(raw_value: str) -> str:
+    try:
+        payload = json.loads(raw_value)
+    except json.JSONDecodeError as exc:
+        raise HTTPException(status_code=400, detail="Document blocks payload must be valid JSON.") from exc
+
+    if not isinstance(payload, list):
+        raise HTTPException(status_code=400, detail="Document blocks payload must be a list.")
+
+    blocks = []
+    for item in payload:
+        text = item.get("text") if isinstance(item, dict) else item if isinstance(item, str) else ""
+        if not isinstance(text, str) or not text.strip():
+            continue
+        blocks.append({"index": len(blocks), "text": text.strip()})
+
+    if not blocks:
+        raise HTTPException(status_code=400, detail="Document blocks payload is empty.")
+
+    return json.dumps(blocks, ensure_ascii=False)
+
+
+def _delete_session_assets(session: models.Session) -> None:
+    if session.video_path:
+        storage_client.delete_file(session.video_path)
+    if session.document_path:
+        storage_client.delete_file(session.document_path)
+
+
+@router.post("", response_model=schemas.SessionOut)
+def create_session(
+    payload: schemas.SessionCreate,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    clean_keywords = [str(k).strip() for k in payload.target_keywords if str(k).strip()]
+    seg_dicts = [seg.model_dump() for seg in payload.transcript_segments]
+    metric_dicts = [point.model_dump() for point in payload.metrics]
+
+    computed_wpm = payload.wpm_avg
+    computed_fillers = payload.filler_count
+    if seg_dicts:
+        words = count_words(seg_dicts)
+        if not computed_wpm and payload.duration_ms > 0:
+            computed_wpm = compute_wpm(words, payload.duration_ms)
+        if not computed_fillers:
+            computed_fillers = count_fillers(seg_dicts)
+
+    session = models.Session(
+        user_id=current_user.id,
+        title=payload.title,
+        mode=payload.mode,
+        prompt=payload.prompt,
+        goal=payload.goal,
+        curriculum_day=payload.curriculum_day,
+        exercise_id=payload.exercise_id,
+        story_framework=payload.story_framework,
+        target_keywords_json=json.dumps(clean_keywords, ensure_ascii=False) if clean_keywords else None,
+        teleprompter_script=payload.teleprompter_script,
+        started_at=payload.started_at,
+        ended_at=payload.ended_at,
+        duration_ms=payload.duration_ms,
+        wpm_avg=computed_wpm,
+        filler_count=computed_fillers,
+        eye_contact_pct=payload.eye_contact_pct,
+        transcription_status="complete" if seg_dicts else "idle",
+    )
+    db.add(session)
+    db.flush()
+
+    for tag in payload.tags:
+        db.add(models.Tag(session_id=session.id, name=tag))
+
+    for seg in payload.transcript_segments:
+        db.add(
+            models.TranscriptSegment(
+                session_id=session.id,
+                start_ms=seg.start_ms,
+                end_ms=seg.end_ms,
+                text=seg.text,
+            )
+        )
+
+    for point in payload.metrics:
+        db.add(
+            models.MetricsTimeseries(
+                session_id=session.id,
+                t=point.t,
+                wpm=point.wpm,
+                rms=point.rms,
+                eye_contact=point.eye_contact,
+                smile=point.smile,
+                yaw=point.yaw,
+                pitch=point.pitch,
+                roll=point.roll,
+                filler_count=point.filler_count,
+                pause_ms=point.pause_ms,
+            )
+        )
+
+    score_payload = payload.score
+    if score_payload is None:
+        score_payload = compute_score(
+            seg_dicts,
+            metric_dicts,
+            payload.duration_ms,
+            clean_keywords,
+        )
+    db.add(models.Score(session_id=session.id, data=score_payload))
+
+    db.commit()
+    db.refresh(session)
+    snapshot = compute_session_metrics(db, session.id)
+
+    if payload.curriculum_day and 1 <= payload.curriculum_day <= 30:
+        record_curriculum_completion(
+            db=db,
+            user_id=current_user.id,
+            day_number=payload.curriculum_day,
+            session_id=session.id,
+            score=snapshot.overall_score,
+        )
+
+    db.refresh(session)
+    return _session_to_out(session)
+
+
+@router.patch("/{session_id}/transcript", response_model=schemas.SessionOut)
+def update_session_transcript(
+    session_id: int,
+    payload: schemas.TranscriptUpdateRequest,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    session.transcript_segments.clear()
+    db.flush()
+
+    seg_dicts = []
+    for seg in payload.transcript_segments:
+        text = seg.text.strip()
+        if not text:
+            continue
+        db.add(
+            models.TranscriptSegment(
+                session_id=session.id,
+                start_ms=max(0, seg.start_ms),
+                end_ms=max(seg.start_ms, seg.end_ms),
+                text=text,
+            )
+        )
+        seg_dicts.append({"start_ms": max(0, seg.start_ms), "end_ms": max(seg.start_ms, seg.end_ms), "text": text})
+    db.flush()
+
+    metric_dicts = [
+        {
+            "t": point.t,
+            "wpm": point.wpm,
+            "rms": point.rms,
+            "eye_contact": point.eye_contact,
+            "smile": point.smile,
+            "yaw": point.yaw,
+            "pitch": point.pitch,
+            "roll": point.roll,
+            "filler_count": point.filler_count,
+            "pause_ms": point.pause_ms,
+        }
+        for point in session.metrics
+    ]
+    words = count_words(seg_dicts)
+    if session.duration_ms > 0:
+        session.wpm_avg = compute_wpm(words, session.duration_ms)
+    session.filler_count = count_fillers(seg_dicts)
+    session.transcription_status = "complete" if seg_dicts else _status_for_missing_video(session)
+
+    score_payload = compute_score(
+        seg_dicts,
+        metric_dicts,
+        session.duration_ms,
+        _parse_keywords(session.target_keywords_json),
+    )
+    if session.score:
+        session.score.data = score_payload
+    else:
+        db.add(models.Score(session_id=session.id, data=score_payload))
+
+    # Invalidate stale coaching so next fetch regenerates with updated transcript
+    existing_coaching = (
+        db.query(models.CoachingFeedback)
+        .filter(models.CoachingFeedback.session_id == session.id)
+        .first()
+    )
+    if existing_coaching:
+        db.delete(existing_coaching)
+
+    db.commit()
+    snapshot = compute_session_metrics(db, session.id)
+    if session.curriculum_day and 1 <= session.curriculum_day <= 30:
+        record_curriculum_completion(
+            db=db,
+            user_id=current_user.id,
+            day_number=session.curriculum_day,
+            session_id=session.id,
+            score=snapshot.overall_score,
+        )
+    db.refresh(session)
+    return _session_to_out(session)
+
+
+@router.get("", response_model=list[schemas.SessionListItem])
+def list_sessions(
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    sessions = (
+        db.query(models.Session)
+        .filter(models.Session.user_id == current_user.id)
+        .order_by(models.Session.created_at.desc())
+        .all()
+    )
+    items = []
+    for sess in sessions:
+        score_data = sess.score.data if sess.score else None
+        items.append(
+            schemas.SessionListItem(
+                id=sess.id,
+                title=sess.title,
+                mode=sess.mode,
+                curriculum_day=sess.curriculum_day,
+                duration_ms=sess.duration_ms,
+                wpm_avg=sess.wpm_avg,
+                filler_count=sess.filler_count,
+                eye_contact_pct=sess.eye_contact_pct,
+                created_at=sess.created_at,
+                transcription_status=sess.transcription_status,
+                video_available=bool(sess.video_path),
+                score=score_data,
+            )
+        )
+    return items
+
+
+@router.get("/{session_id}", response_model=schemas.SessionOut)
+def get_session(
+    session_id: int,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    return _session_to_out(session)
+
+
+@router.post("/{session_id}/upload", response_model=schemas.UploadResponse)
+def upload_video(
+    session_id: int,
+    file: UploadFile = File(...),
+    chunk_index: Optional[int] = None,
+    total_chunks: Optional[int] = None,
+    upload_id: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    extension, resolved_mime = _resolve_video_format(mime_type or file.content_type or file.filename)
+
+    if chunk_index is not None and total_chunks is not None:
+        if not upload_id:
+            raise HTTPException(status_code=400, detail="upload_id required")
+        chunk_size, _header = _file_size_and_header(file.file)
+        _validate_size(chunk_size, "Video chunk")
+        file.file.seek(0)
+        tmp_dir = Path(settings.storage_dir) / "tmp" / upload_id
+        tmp_dir.mkdir(parents=True, exist_ok=True)
+        chunk_path = tmp_dir / f"{chunk_index}.part"
+        with open(chunk_path, "wb") as out:
+            shutil.copyfileobj(file.file, out)
+
+        if chunk_index == total_chunks - 1:
+            merged_path = tmp_dir / f"merged.{extension}"
+            with open(merged_path, "wb") as merged:
+                for idx in range(total_chunks):
+                    part_path = tmp_dir / f"{idx}.part"
+                    if not part_path.exists():
+                        raise HTTPException(status_code=400, detail="missing chunk")
+                    with open(part_path, "rb") as part:
+                        shutil.copyfileobj(part, merged)
+            _validate_video_path(merged_path, resolved_mime)
+            key = f"sessions/{session_id}/recording.{extension}"
+            with open(merged_path, "rb") as merged_file:
+                stored_path = storage_client.save_file(key, merged_file)
+            session.video_path = stored_path
+            db.commit()
+            shutil.rmtree(tmp_dir)
+            return {"session_id": session_id, "status": "complete", "video_path": stored_path}
+
+        return {"session_id": session_id, "status": "partial"}
+
+    _validate_video_upload(file, resolved_mime)
+    key = f"sessions/{session_id}/recording.{extension}"
+    stored_path = storage_client.save_file(key, file.file)
+    session.video_path = stored_path
+    db.commit()
+    return {"session_id": session_id, "status": "complete", "video_path": stored_path}
+
+
+@router.post("/{session_id}/document", response_model=schemas.SessionDocumentOut)
+def upload_document(
+    session_id: int,
+    file: UploadFile = File(...),
+    blocks_json: str = Form(...),
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    extension, mime_type = _resolve_document_format(file.filename, file.content_type)
+    _validate_document_upload(file, extension, mime_type)
+    normalized_blocks_json = _normalize_document_blocks_payload(blocks_json)
+
+    if session.document_path:
+        storage_client.delete_file(session.document_path)
+
+    key = f"sessions/{session_id}/document{extension}"
+    stored_path = storage_client.save_file(key, file.file)
+    session.document_path = stored_path
+    session.document_name = file.filename or f"document{extension}"
+    session.document_mime_type = mime_type
+    session.document_blocks_json = normalized_blocks_json
+    db.commit()
+    db.refresh(session)
+
+    document = _serialize_document(session)
+    if document is None:
+        raise HTTPException(status_code=500, detail="Document was saved but could not be serialized.")
+    return document
+
+
+@router.post("/{session_id}/transcribe")
+async def transcribe_session(
+    session_id: int,
+    payload: schemas.TranscriptionRequest | None = None,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    if not session.video_path:
+        raise HTTPException(status_code=400, detail="No video uploaded")
+    try:
+        selected_backend = transcription.resolve_transcription_backend(
+            payload.backend if payload else None,
+            payload.model if payload else None,
+        )
+        selected_model = transcription.resolve_transcription_model(
+            payload.model if payload else None,
+            selected_backend,
+        )
+        transcription.ensure_transcription_model_ready(selected_backend, selected_model)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    session.transcription_status = "queued"
+    db.commit()
+
+    try:
+        job_id = await enqueue_transcription(session_id, current_user.id, selected_model, selected_backend)
+    except Exception as exc:
+        session.transcription_status = "idle"
+        db.commit()
+        raise HTTPException(status_code=503, detail="Job backend unavailable") from exc
+    return {"status": "queued", "job_id": job_id}
+
+
+@router.delete("/{session_id}")
+def delete_session(
+    session_id: int,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    _delete_session_assets(session)
+    db.delete(session)
+    db.commit()
+    return {"status": "deleted"}
+
+
+@router.delete("/{session_id}/video")
+def delete_video(
+    session_id: int,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    if session.video_path:
+        storage_client.delete_file(session.video_path)
+        session.video_path = None
+    session.transcription_status = _status_for_missing_video(session)
+    db.commit()
+    return {"status": "deleted", "transcription_status": session.transcription_status}
+
+
+@router.get("/{session_id}/export")
+def export_session(
+    session_id: int,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    tmp_dir = tempfile.mkdtemp()
+    zip_path = os.path.join(tmp_dir, f"session_{session_id}.zip")
+    transcript_text = _build_transcript_text(session)
+    transcript_pdf = _build_transcript_pdf(session)
+
+    transcript_payload = [
+        {"start_ms": segment.start_ms, "end_ms": segment.end_ms, "text": segment.text}
+        for segment in session.transcript_segments
+    ]
+    metrics_payload = [
+        {
+            "t": point.t,
+            "wpm": point.wpm,
+            "rms": point.rms,
+            "eye_contact": point.eye_contact,
+            "smile": point.smile,
+            "yaw": point.yaw,
+            "pitch": point.pitch,
+            "roll": point.roll,
+            "filler_count": point.filler_count,
+            "pause_ms": point.pause_ms,
+        }
+        for point in session.metrics
+    ]
+    score_payload = session.score.data if session.score else {}
+
+    with zipfile.ZipFile(zip_path, "w") as zipf:
+        zipf.writestr("transcript.json", json.dumps(transcript_payload, indent=2))
+        zipf.writestr("transcript.txt", transcript_text)
+        zipf.writestr("transcript.pdf", transcript_pdf)
+        zipf.writestr("metrics.json", json.dumps(metrics_payload, indent=2))
+        zipf.writestr("score.json", json.dumps(score_payload, indent=2))
+        if session.document_blocks_json:
+            zipf.writestr("document_blocks.json", session.document_blocks_json)
+        if session.video_path:
+            try:
+                video_path = storage_client.get_local_path(session.video_path)
+            except RuntimeError:
+                video_path = None
+            if video_path and os.path.exists(video_path):
+                video_name = f"recording{Path(video_path).suffix or '.webm'}"
+                zipf.write(video_path, arcname=video_name)
+        if session.document_path:
+            try:
+                document_path = storage_client.get_local_path(session.document_path)
+            except RuntimeError:
+                document_path = None
+            if document_path and os.path.exists(document_path):
+                document_name = session.document_name or f"reading{Path(document_path).suffix or '.txt'}"
+                zipf.write(document_path, arcname=document_name)
+
+    return FileResponse(zip_path, filename=f"session_{session_id}.zip")
+
+
+@router.get("/{session_id}/transcript.txt")
+def download_transcript_txt(
+    session_id: int,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    _raise_if_transcript_missing(session)
+    filename = _session_transcript_filename(session, "txt")
+    return Response(
+        content=_build_transcript_text(session),
+        media_type="text/plain; charset=utf-8",
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )
+
+
+@router.get("/{session_id}/transcript.pdf")
+def download_transcript_pdf(
+    session_id: int,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    _raise_if_transcript_missing(session)
+    filename = _session_transcript_filename(session, "pdf")
+    return Response(
+        content=_build_transcript_pdf(session),
+        media_type="application/pdf",
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )
+
+
+@router.get("/{session_id}/video")
+def get_video(
+    session_id: int,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_user),
+):
+    session = _get_session_or_404(db, current_user.id, session_id)
+    if not session.video_path:
+        raise HTTPException(status_code=404, detail="Video not found")
+    try:
+        video_path = storage_client.get_local_path(session.video_path)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=501, detail="Video download unavailable") from exc
+    if not os.path.exists(video_path):
+        raise HTTPException(status_code=404, detail="Video not found")
+    _extension, media_type = _resolve_video_format(video_path)
+    media_type = _detect_media_type(video_path, media_type)
+    return FileResponse(video_path, media_type=media_type)
+
+
+def _get_session_or_404(db: Session, user_id: int, session_id: int) -> models.Session:
+    session = (
+        db.query(models.Session)
+        .filter(models.Session.id == session_id, models.Session.user_id == user_id)
+        .first()
+    )
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return session
+
+
+def _run_transcription(
+    session_id: int,
+    user_id: int,
+    model_name: str | None = None,
+    backend_id: str | None = None,
+) -> None:
+    db = SessionLocal()
+    session: models.Session | None = None
+    audio_path: str | None = None
+    try:
+        session = (
+            db.query(models.Session)
+            .filter(models.Session.id == session_id, models.Session.user_id == user_id)
+            .first()
+        )
+        if not session or not session.video_path:
+            return
+        session.transcription_status = "processing"
+        db.commit()
+        video_path = storage_client.get_local_path(session.video_path)
+        audio_path = transcription.extract_audio(video_path)
+        segments = transcription.transcribe_audio(audio_path, model_name, backend_id)
+        session.transcript_segments.clear()
+        db.flush()
+        for seg in segments:
+            db.add(
+                models.TranscriptSegment(
+                    session_id=session.id,
+                    start_ms=seg["start_ms"],
+                    end_ms=seg["end_ms"],
+                    text=seg["text"],
+                )
+            )
+        db.flush()
+        words = count_words(segments)
+        if session.duration_ms > 0:
+            session.wpm_avg = compute_wpm(words, session.duration_ms)
+        session.filler_count = count_fillers(segments)
+        score_payload = compute_score(
+            segments,
+            [
+                {
+                    "t": point.t,
+                    "wpm": point.wpm,
+                    "rms": point.rms,
+                    "eye_contact": point.eye_contact,
+                    "smile": point.smile,
+                    "yaw": point.yaw,
+                    "pitch": point.pitch,
+                    "roll": point.roll,
+                    "filler_count": point.filler_count,
+                    "pause_ms": point.pause_ms,
+                }
+                for point in session.metrics
+            ],
+            session.duration_ms,
+            _parse_keywords(session.target_keywords_json),
+        )
+        if session.score:
+            session.score.data = score_payload
+        else:
+            db.add(models.Score(session_id=session.id, data=score_payload))
+        session.transcription_status = "complete"
+        db.commit()
+        snapshot = compute_session_metrics(db, session.id)
+        if session.curriculum_day and 1 <= session.curriculum_day <= 30:
+            record_curriculum_completion(
+                db=db,
+                user_id=user_id,
+                day_number=session.curriculum_day,
+                session_id=session.id,
+                score=snapshot.overall_score,
+            )
+    except Exception:
+        if session is None and session_id:
+            session = db.query(models.Session).filter(models.Session.id == session_id).first()
+        if session:
+            if session.video_path:
+                session.transcription_status = "failed"
+            else:
+                session.transcription_status = _status_for_missing_video(session)
+            db.commit()
+    finally:
+        if audio_path:
+            try:
+                audio_file = Path(audio_path)
+                if audio_file.exists():
+                    audio_file.unlink()
+                if audio_file.parent.exists():
+                    audio_file.parent.rmdir()
+            except OSError:
+                pass
+        db.close()
+
+
+def _session_to_out(session: models.Session) -> schemas.SessionOut:
+    tags = [tag.name for tag in session.tags]
+    score_data = session.score.data if session.score else None
+    return schemas.SessionOut(
+        id=session.id,
+        title=session.title,
+        mode=session.mode,
+        prompt=session.prompt,
+        goal=session.goal,
+        curriculum_day=session.curriculum_day,
+        exercise_id=session.exercise_id,
+        story_framework=session.story_framework,
+        target_keywords=_parse_keywords(session.target_keywords_json),
+        teleprompter_script=session.teleprompter_script,
+        started_at=session.started_at,
+        ended_at=session.ended_at,
+        duration_ms=session.duration_ms,
+        wpm_avg=session.wpm_avg,
+        filler_count=session.filler_count,
+        eye_contact_pct=session.eye_contact_pct,
+        video_path=session.video_path,
+        transcription_status=session.transcription_status,
+        created_at=session.created_at,
+        tags=tags,
+        transcript_segments=_serialize_transcript_segments(session.transcript_segments),
+        metrics=_serialize_metrics(session.metrics),
+        score=score_data,
+        document=_serialize_document(session),
+    )

apps/api/src/app/routes/settings.py

@@ -0,0 +1,41 @@
+from fastapi import APIRouter, Depends
+from fastapi import HTTPException
+
+from app import models, schemas, transcription
+from app.auth import get_current_user
+from app.local_inference import check_engine, get_all_engine_statuses
+
+router = APIRouter(prefix="/settings", tags=["settings"])
+
+
+@router.get("/transcription", response_model=schemas.TranscriptionSettingsOut)
+def get_transcription_settings(current_user: models.User = Depends(get_current_user)):
+    return {
+        "default_backend": transcription.get_default_transcription_backend(),
+        "backends": transcription.get_transcription_backends(),
+        "text_inference_engines": get_all_engine_statuses(),
+    }
+
+
+@router.post("/transcription/models/download", response_model=schemas.TranscriptionModelOut)
+def download_transcription_model(
+    payload: schemas.TranscriptionModelDownloadRequest,
+    current_user: models.User = Depends(get_current_user),
+):
+    try:
+        return transcription.download_transcription_model(payload.backend, payload.model)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+
+@router.post("/local-inference/check", response_model=schemas.InferenceEngineStatusOut)
+def check_local_inference(
+    payload: schemas.InferenceEngineCheckRequest,
+    current_user: models.User = Depends(get_current_user),
+):
+    try:
+        return check_engine(payload.engine_id, payload.base_url)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc

apps/api/src/app/routes/setup.py

@@ -0,0 +1,37 @@
+from fastapi import APIRouter, Depends, HTTPException, Response, status
+from sqlalchemy.orm import Session
+
+from app import models, schemas
+from app.auth import hash_password, issue_token_pair
+from app.db import get_db
+from app.rate_limit import rate_limit
+
+router = APIRouter(prefix="/setup", tags=["setup"])
+
+
+@router.get("/status", response_model=schemas.SetupStatus)
+def setup_status(db: Session = Depends(get_db)):
+    user_exists = db.query(models.User.id).first() is not None
+    return {"setup_required": not user_exists}
+
+
+@router.post(
+    "",
+    response_model=schemas.Token,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(rate_limit(5))],
+)
+def initial_setup(payload: schemas.UserCreate, response: Response, db: Session = Depends(get_db)):
+    user_exists = db.query(models.User.id).first() is not None
+    if user_exists:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Setup already completed")
+
+    user = models.User(
+        email=payload.email,
+        hashed_password=hash_password(payload.password),
+        is_admin=True,
+    )
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+    return issue_token_pair(db, response, user)

apps/api/src/app/schema_upgrades.py

@@ -0,0 +1,31 @@
+from sqlalchemy import inspect
+
+from app.db import engine
+
+
+SESSION_COLUMN_DDL: dict[str, str] = {
+    "document_path": "ALTER TABLE sessions ADD COLUMN document_path VARCHAR(1024)",
+    "document_name": "ALTER TABLE sessions ADD COLUMN document_name VARCHAR(255)",
+    "document_mime_type": "ALTER TABLE sessions ADD COLUMN document_mime_type VARCHAR(255)",
+    "document_blocks_json": "ALTER TABLE sessions ADD COLUMN document_blocks_json TEXT",
+    "curriculum_day": "ALTER TABLE sessions ADD COLUMN curriculum_day INTEGER",
+    "exercise_id": "ALTER TABLE sessions ADD COLUMN exercise_id VARCHAR(100)",
+    "story_framework": "ALTER TABLE sessions ADD COLUMN story_framework VARCHAR(80)",
+    "target_keywords_json": "ALTER TABLE sessions ADD COLUMN target_keywords_json TEXT",
+    "teleprompter_script": "ALTER TABLE sessions ADD COLUMN teleprompter_script TEXT",
+}
+
+
+def apply_startup_schema_upgrades() -> None:
+    inspector = inspect(engine)
+    if "sessions" not in inspector.get_table_names():
+        return
+
+    existing_columns = {column["name"] for column in inspector.get_columns("sessions")}
+    statements = [ddl for column_name, ddl in SESSION_COLUMN_DDL.items() if column_name not in existing_columns]
+    if not statements:
+        return
+
+    with engine.begin() as connection:
+        for statement in statements:
+            connection.exec_driver_sql(statement)

apps/api/src/app/schemas.py

@@ -0,0 +1,324 @@
+from datetime import date, datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, model_validator
+
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(min_length=6)
+
+
+class UserLogin(BaseModel):
+    email: str
+    password: str
+
+
+class UserOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    email: EmailStr
+    is_admin: bool = False
+
+
+class Token(BaseModel):
+    access_token: str
+    refresh_token: str | None = None
+    token_type: str = "bearer"
+    expires_in: int | None = None
+    user: UserOut | None = None
+
+
+class SetupStatus(BaseModel):
+    setup_required: bool
+
+
+GoalMetric = Literal[
+    "wpm",
+    "filler_rate",
+    "overall_score",
+    "practice_days_per_week",
+    "session_duration_minutes",
+    "eye_contact_score",
+    "delivery_score",
+]
+GoalComparison = Literal["gte", "lte", "between"]
+
+
+class UserGoalCreate(BaseModel):
+    metric_name: GoalMetric
+    comparison: GoalComparison
+    target_value: float = Field(ge=0)
+    target_upper: float | None = Field(default=None, ge=0)
+    is_active: bool = True
+
+    @model_validator(mode="after")
+    def validate_range(self):
+        if self.comparison == "between":
+            if self.target_upper is None or self.target_upper <= self.target_value:
+                raise ValueError("between goals require target_upper greater than target_value")
+        elif self.target_upper is not None:
+            raise ValueError("target_upper is only valid for between goals")
+        return self
+
+
+class UserGoalUpdate(BaseModel):
+    comparison: GoalComparison | None = None
+    target_value: float | None = Field(default=None, ge=0)
+    target_upper: float | None = Field(default=None, ge=0)
+    is_active: bool | None = None
+
+
+class UserGoalOut(BaseModel):
+    id: int
+    metric_name: GoalMetric
+    comparison: GoalComparison
+    target_value: float
+    target_upper: float | None
+    is_active: bool
+    current_value: float | None
+    achieved: bool
+    created_at: datetime
+    updated_at: datetime
+
+
+class PresenterProfileUpdate(BaseModel):
+    display_name: str | None = Field(default=None, max_length=120)
+    primary_role: str | None = Field(default=None, max_length=120)
+    focus_track: Literal[
+        "tech_storytelling",
+        "keynote_clarity",
+        "camera_confidence",
+        "executive_pitch",
+        "tech_presenter",
+        "tech_news_creator",
+        "engineering_leader",
+    ] | None = None
+    experience_level: Literal["beginner", "intermediate", "advanced"] | None = None
+    target_wpm_min: int | None = Field(default=None, ge=80, le=200)
+    target_wpm_max: int | None = Field(default=None, ge=90, le=220)
+    max_filler_rate: float | None = Field(default=None, ge=0, le=20)
+    min_eye_contact: float | None = Field(default=None, ge=0, le=1)
+    daily_minutes_goal: int | None = Field(default=None, ge=5, le=120)
+    weaknesses: list[str] | None = None
+    speaking_goal_statement: str | None = Field(default=None, max_length=500)
+    reset_start_date: bool = False
+
+
+class PresenterProfileOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    display_name: str
+    primary_role: str
+    focus_track: str
+    experience_level: str
+    target_wpm_min: int
+    target_wpm_max: int
+    max_filler_rate: float
+    min_eye_contact: float
+    daily_minutes_goal: int
+    weaknesses: list[str] = Field(default_factory=list)
+    speaking_goal_statement: str | None = None
+    curriculum_start_date: date
+
+
+class CurriculumCompleteRequest(BaseModel):
+    session_id: int | None = None
+    score: float | None = None
+    reflection_notes: str | None = Field(default=None, max_length=2000)
+
+
+class StoryboardRequest(BaseModel):
+    headline: str = Field(min_length=3, max_length=300)
+    summary: str = Field(default="", max_length=4000)
+    source: str | None = Field(default=None, max_length=120)
+    url: str | None = Field(default=None, max_length=1000)
+    category: str | None = Field(default="AI & Systems", max_length=80)
+    framework: Literal["briefing_60s", "explainer_2m", "contrarian_take", "war_story"] = "briefing_60s"
+    personal_angle: str | None = Field(default=None, max_length=1000)
+
+
+class WeeklyNoteUpdate(BaseModel):
+    week_start_date: date
+    wins_note: str | None = Field(default=None, max_length=2000)
+    focus_next_week: str | None = Field(default=None, max_length=2000)
+
+
+class TranscriptUpdateRequest(BaseModel):
+    transcript_segments: list["TranscriptSegmentCreate"] = Field(default_factory=list)
+
+
+class TranscriptionRequest(BaseModel):
+    backend: str | None = None
+    model: str | None = None
+
+
+class TranscriptionModelDownloadRequest(BaseModel):
+    backend: str
+    model: str
+
+
+class InferenceEngineCheckRequest(BaseModel):
+    engine_id: str
+    base_url: str | None = None
+
+
+class InferenceEngineStatusOut(BaseModel):
+    id: str
+    label: str
+    base_url: str
+    live: bool
+    detail: str
+    available_models: list[str] = Field(default_factory=list)
+
+
+class TranscriptionModelOut(BaseModel):
+    id: str
+    name: str
+    repo_id: str
+    description: str
+    languages: str
+    available: bool = False
+    local_path: str | None = None
+
+
+class TranscriptionBackendOut(BaseModel):
+    id: str
+    label: str
+    supported: bool
+    live: bool
+    detail: str
+    models: list[TranscriptionModelOut] = Field(default_factory=list)
+    default_model: str | None = None
+
+
+class TranscriptionSettingsOut(BaseModel):
+    default_backend: str
+    backends: list[TranscriptionBackendOut] = Field(default_factory=list)
+    text_inference_engines: list[InferenceEngineStatusOut] = Field(default_factory=list)
+
+
+class TranscriptSegmentCreate(BaseModel):
+    start_ms: int
+    end_ms: int
+    text: str
+
+
+class TranscriptSegmentOut(TranscriptSegmentCreate):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+
+
+class DocumentBlockOut(BaseModel):
+    index: int
+    text: str
+
+
+class SessionDocumentOut(BaseModel):
+    name: str
+    mime_type: str
+    blocks: list[DocumentBlockOut] = Field(default_factory=list)
+
+
+class MetricsPointCreate(BaseModel):
+    t: int
+    wpm: float = 0
+    rms: float = 0
+    eye_contact: float = 0
+    smile: float = 0
+    yaw: float = 0
+    pitch: float = 0
+    roll: float = 0
+    filler_count: int = 0
+    pause_ms: int = 0
+
+
+class ScoreCreate(BaseModel):
+    data: dict
+
+
+class ScoreOut(ScoreCreate):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+
+
+class SessionCreate(BaseModel):
+    title: str | None = None
+    mode: str | None = None
+    prompt: str | None = None
+    goal: str | None = None
+    curriculum_day: int | None = Field(default=None, ge=1, le=30)
+    exercise_id: str | None = None
+    story_framework: str | None = None
+    target_keywords: list[str] = Field(default_factory=list)
+    teleprompter_script: str | None = None
+    started_at: datetime | None = None
+    ended_at: datetime | None = None
+    duration_ms: int = 0
+    wpm_avg: float = 0
+    filler_count: int = 0
+    eye_contact_pct: float = 0
+    tags: list[str] = Field(default_factory=list)
+    transcript_segments: list[TranscriptSegmentCreate] = Field(default_factory=list)
+    metrics: list[MetricsPointCreate] = Field(default_factory=list)
+    score: dict | None = None
+
+
+class SessionOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    title: str | None
+    mode: str | None
+    prompt: str | None
+    goal: str | None
+    curriculum_day: int | None = None
+    exercise_id: str | None = None
+    story_framework: str | None = None
+    target_keywords: list[str] = Field(default_factory=list)
+    teleprompter_script: str | None = None
+    started_at: datetime | None
+    ended_at: datetime | None
+    duration_ms: int
+    wpm_avg: float
+    filler_count: int
+    eye_contact_pct: float
+    video_path: str | None
+    transcription_status: str
+    created_at: datetime
+    tags: list[str] = Field(default_factory=list)
+    transcript_segments: list[TranscriptSegmentOut] = Field(default_factory=list)
+    metrics: list[MetricsPointCreate] = Field(default_factory=list)
+    score: dict | None = None
+    document: SessionDocumentOut | None = None
+
+
+class SessionListItem(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    title: str | None
+    mode: str | None
+    curriculum_day: int | None = None
+    duration_ms: int
+    wpm_avg: float
+    filler_count: int
+    eye_contact_pct: float
+    created_at: datetime
+    transcription_status: str
+    video_available: bool = False
+    score: dict | None = None
+
+
+class UploadResponse(BaseModel):
+    session_id: int
+    status: str
+    video_path: str | None = None
+
+
+class ExportResponse(BaseModel):
+    zip_path: str

apps/api/src/app/scoring.py

@@ -0,0 +1,216 @@
+import re
+from typing import List
+
+FILLER_WORDS = ["um", "uh", "like", "you know", "actually", "basically", "literally"]
+STRUCTURE_WORDS = ["first", "second", "third", "because", "therefore", "however", "so", "thus"]
+
+
+def tokenize(text: str) -> List[str]:
+    return [w for w in re.sub(r"[^a-z0-9\s']", " ", text.lower()).split() if w]
+
+
+def count_words(segments: List[dict]) -> int:
+    return sum(len(tokenize(seg["text"])) for seg in segments)
+
+
+def count_fillers(segments: List[dict]) -> int:
+    text = " ".join(seg["text"].lower() for seg in segments)
+    total = 0
+    for filler in FILLER_WORDS:
+        escaped = re.escape(filler).replace(" ", r"\s+")
+        pattern = re.compile(rf"\b{escaped}\b")
+        total += len(pattern.findall(text))
+    return total
+
+
+def compute_wpm(word_count: int, duration_ms: int) -> float:
+    if duration_ms <= 0:
+        return 0
+    return round((word_count / (duration_ms / 60000)) * 10) / 10
+
+
+def score_wpm(wpm: float) -> int:
+    if 120 <= wpm <= 160:
+        return 18
+    if 100 <= wpm < 120 or 160 < wpm <= 180:
+        return 10
+    return 4
+
+
+def score_fillers(fillers_per_minute: float) -> int:
+    if fillers_per_minute <= 2:
+        return 12
+    if fillers_per_minute <= 6:
+        return 8
+    return 3
+
+
+def score_pauses(pause_events: List[int], duration_ms: int) -> int:
+    if not pause_events:
+        return 4
+    natural = len([p for p in pause_events if 600 <= p <= 1500])
+    long = len([p for p in pause_events if p > 1500])
+    minutes = max(duration_ms / 60000, 0.1)
+    rate = natural / minutes
+    if long > max(2, minutes):
+        return 4
+    if 2 <= rate <= 6:
+        return 10
+    if rate >= 1:
+        return 7
+    return 5
+
+
+def score_eye_contact(eye_contact_pct: float) -> int:
+    if eye_contact_pct > 0.7:
+        return 15
+    if eye_contact_pct >= 0.4:
+        return 10
+    return 5
+
+
+def score_smile(smile_avg: float) -> int:
+    return round(7 * max(0, min(1, smile_avg)))
+
+
+def score_head_stability(yaw_var: float, pitch_var: float, roll_var: float) -> int:
+    total_var = yaw_var + pitch_var + roll_var
+    if total_var < 5:
+        return 8
+    if total_var < 12:
+        return 6
+    return 4
+
+
+def score_structure(segments: List[dict]) -> int:
+    words = tokenize(" ".join(seg["text"] for seg in segments))
+    count = sum(1 for w in words if w in STRUCTURE_WORDS)
+    if count >= 4:
+        return 10
+    if count >= 2:
+        return 7
+    return 4
+
+
+def score_repetition(segments: List[dict]) -> int:
+    words = tokenize(" ".join(seg["text"] for seg in segments))
+    freq = {}
+    for word in words:
+        freq[word] = freq.get(word, 0) + 1
+    repeated = len([c for c in freq.values() if c >= 6])
+    if repeated >= 3:
+        return -8
+    if repeated >= 1:
+        return -4
+    return 0
+
+
+def score_clarity(segments: List[dict]) -> int:
+    sentences = [s.strip() for s in re.split(r"[.!?]+", " ".join(seg["text"] for seg in segments)) if s.strip()]
+    if not sentences:
+        return 0
+    lengths = [len(tokenize(s)) for s in sentences]
+    avg = sum(lengths) / len(lengths)
+    if 8 <= avg <= 20:
+        return 12
+    if 5 <= avg <= 25:
+        return 8
+    return 4
+
+
+def score_keyword_coverage(segments: List[dict], keywords: List[str]) -> int:
+    if not keywords:
+        return 0
+    text = " ".join(seg["text"].lower() for seg in segments)
+    covered = sum(1 for k in keywords if k.lower() in text)
+    ratio = covered / len(keywords)
+    if ratio >= 0.8:
+        return 8
+    if ratio >= 0.5:
+        return 5
+    return 2
+
+
+def avg(values: List[float]) -> float:
+    return sum(values) / len(values) if values else 0
+
+
+def variance(values: List[float]) -> float:
+    if not values:
+        return 0
+    mean = avg(values)
+    return avg([(v - mean) ** 2 for v in values])
+
+
+def compute_score(segments: List[dict], metrics: List[dict], duration_ms: int, keywords: List[str]):
+    word_count = count_words(segments)
+    wpm = compute_wpm(word_count, duration_ms)
+    filler_count = count_fillers(segments)
+    minutes = max(duration_ms / 60000, 0.1)
+    fillers_per_minute = filler_count / minutes
+    pause_events = [m.get("pause_ms", 0) for m in metrics if m.get("pause_ms", 0) > 0]
+
+    wpm_score = score_wpm(wpm)
+    filler_score = score_fillers(fillers_per_minute)
+    pause_score = score_pauses(pause_events, duration_ms)
+    speech = wpm_score + filler_score + pause_score
+
+    eye_contact_pct = avg([m.get("eye_contact", 0) for m in metrics])
+    smile_avg = avg([m.get("smile", 0) for m in metrics])
+    yaw_var = variance([m.get("yaw", 0) for m in metrics])
+    pitch_var = variance([m.get("pitch", 0) for m in metrics])
+    roll_var = variance([m.get("roll", 0) for m in metrics])
+
+    eye_score = score_eye_contact(eye_contact_pct)
+    smile_score = score_smile(smile_avg)
+    head_score = score_head_stability(yaw_var, pitch_var, roll_var)
+    delivery = eye_score + smile_score + head_score
+
+    structure_score = score_structure(segments)
+    repetition_score = score_repetition(segments)
+    clarity_score = score_clarity(segments)
+    keyword_score = score_keyword_coverage(segments, keywords)
+    content = max(0, structure_score + repetition_score + clarity_score + keyword_score)
+
+    total = max(0, min(100, speech + delivery + content))
+
+    fixes = []
+    if wpm_score <= 10:
+        fixes.append("Adjust pace to 120-160 WPM.")
+    if filler_score <= 8:
+        fixes.append("Reduce filler words with pauses.")
+    if eye_score <= 10:
+        fixes.append("Increase eye contact with the lens.")
+    if clarity_score <= 8:
+        fixes.append("Shorten sentences for clarity.")
+    if keyword_score <= 5 and keywords:
+        fixes.append("Cover target keywords.")
+
+    drill = (
+        "60-second pace drill"
+        if speech < delivery and speech < content
+        else "Eye contact mirror drill"
+        if delivery < content
+        else "Story arc outline drill"
+    )
+
+    return {
+        "total": total,
+        "speech": speech,
+        "delivery": delivery,
+        "content": content,
+        "details": {
+            "wpm": wpm_score,
+            "fillers": filler_score,
+            "pauses": pause_score,
+            "eyeContact": eye_score,
+            "smile": smile_score,
+            "headStability": head_score,
+            "structure": structure_score,
+            "repetition": repetition_score,
+            "clarity": clarity_score,
+            "keywordCoverage": keyword_score,
+        },
+        "topFixes": fixes[:3],
+        "recommendedDrill": drill,
+    }