VitFit V2 — Planning Index
This folder contains all planning documentation for the V2 redesign.
Documents
| Document | What it covers |
|---|---|
| PRODUCT_VISION.md | Resale strategy, multi-instance vs SaaS decision, branding, feature tiers, roadmap phases |
| REQUIREMENTS.md | What V2 must do — functional features, stability, security, and platform constraints |
| ROLES_AND_PERMISSIONS.md | Full role hierarchy (SystemAdmin/Owner/Coach/Client), permission matrix, edge cases (last owner, cross-coach, client reassignment) |
| DATA_MODEL.md | All database entities with fields — Organizations, Users, DeviceTokens, ClientWorkouts, CalendarSessions, AuditLogs, Branding; soft delete policy |
| ARCHITECTURE.md | Stack, module system, real-time, storage monitoring, video streaming, SQLite WAL config, video format constraints, path traversal protection |
| AUDIT_LOGS.md | What gets logged, event catalog, implementation pattern, API, frontend viewer |
| API_STANDARDS.md | Versioning (/api/v1), error shape, pagination, date/timezone conventions, error code catalog, naming rules |
| DISPLAY_DESIGN.md | iPad + Safari + AirPlay + TV specifics — PWA config, 24h session stability, offline/degraded mode, typography, Safari quirks |
| OPERATIONS.md | First-run bootstrap, backup strategy, update/patch process, monitoring, device security, support diagnostics |
| MIGRATION_PLAN.md | How to move V1 data to V2 without loss — Sequelize migration strategy, rollback plan |
ADDITIONAL_CONSIDERATIONS.md — gap analysis doc; all actionable items resolved into the documents above.
Key Decisions at a Glance
Product
- Model: Multi-instance (one deployment per gym). Data model is SaaS-ready (
organizationIdon all tables) but no multi-tenant routing in V2. - Resale: White-label branding per org (logo, colors, name), configurable per instance
- Roles: SystemAdmin (platform) → Owner → Coach → Client
- Current customer: Single gym, maps to one Organization; existing accounts map to Owner/Coach roles
Architecture
- Stack: Express.js + SQLite (Sequelize with migrations) + Socket.io + Nginx
- Frontend: Vanilla JS + shared CSS (no heavy framework)
- Timer: Server-side state machine via Socket.io — drift-free, survives reconnects
- Display: PWA (
apple-mobile-web-app-capable) to remove Safari chrome from TV mirror - Auth: JWT 7-day TTL + silent background refresh; Device Tokens for iPad kiosk auto-login
- Modules: Drop-in feature folders — add/remove without touching core
- Process: PM2 with memory limit restart, auto-start on server reboot
Infrastructure
- Server access: PuTTY (SSH) + WinSCP (SFTP) only — no other access method
- Video files: Stay at
/home/ubuntu/site/uploads/— authenticated streaming route with Range support (Safari requires this), never static - Storage monitoring: Admin panel shows disk usage + uploads size; upload endpoint blocks new files when disk is low
New Features vs V1
- Organization model + multi-role hierarchy
- 1-on-1 client programming (ClientWorkouts)
- Calendar/scheduling (CalendarSessions)
- Audit logs (append-only, viewable by Owner+)
- Branding settings per org
- Device token for iPad kiosk credential saving
- Storage monitoring in admin panel
V1 Reference
The full V1 code walkthrough is at the repo root: CODEBASE_REFERENCE.md