Files
2026-06-11 10:52:07 -04:00
..
2026-06-11 10:52:07 -04:00
2026-06-11 10:52:07 -04:00
2026-06-11 10:52:07 -04:00
2026-06-10 22:27:30 -04:00
2026-06-11 10:52:07 -04:00
2026-06-11 10:52:07 -04:00
2026-06-11 10:52:07 -04:00
2026-06-10 22:26:02 -04:00
2026-06-11 10:52:07 -04:00
2026-06-10 22:26:02 -04:00
2026-06-11 10:52:07 -04:00
2026-06-10 22:26:02 -04:00
2026-06-11 10:52:07 -04:00

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 (organizationId on 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