Train5D Application Architecture

Overview
- The 5 Pillars
- Core Philosophy
Directory Structure
- Pillar-Based Organization
- File Organization Conventions
Authentication & Session System
Exercise Management System (Pillar 4)
Nutrition Management System (Pillar 2)
Assessment System
Dashboard & User Interface
Shared Components & Utilities
Database Schema
Technology Stack
Future Pillar Implementation

Overview

Train5D is a comprehensive digital health platform built on the 5 Pillars Framework: Mindset, Nutrition, Posture, Exercise, and Energy Mastery. The platform integrates holistic health management into a unified system that emphasizes cross-pillar connections and personalized guidance.

The 5 Pillars

1. Mindset 🧠

The foundation of transformation. Includes goal setting, habit formation, journaling, mood tracking, and behavioral change strategies.

2. Nutrition 🥗

Evidence-based nutritional guidance with 25 database tables covering foods, nutrients, meal planning, health conditions, and special dietary needs.

3. Posture 🧘

Body alignment and movement patterns. Includes posture assessments, ergonomic guidance, movement quality tracking, and corrective strategies.

4. Exercise 💪

Comprehensive exercise library with 16 database tables covering exercises, muscle groups, equipment, progressions, and programming.

5. Energy Mastery ⚡

The integrative pillar that encompasses sleep, recovery, stress management, and overall energy optimization. Connects all other pillars into a cohesive wellness framework.

Core Philosophy

Working with the body, not against it
Integration is key: All 5 pillars work together, not in isolation
Sustainable, evidence-based changes
Personalized guidance based on holistic data across all pillars

Directory Structure

Pillar-Based Organization

Train5D uses a pillar-first directory structure that mirrors the 5 Pillars Framework. This ensures code organization aligns with the product’s conceptual model, making it intuitive for developers to locate and add features.

Why Pillar-Based Structure?

Conceptual Clarity - Directory structure matches the 5-pillar philosophy
Scalability - Easy to add new pillar features as the platform grows
Discoverability - Developers know exactly where to find/add pillar-specific code
Consistency - Same organizational pattern across pages, API, components, and styles
Future-Ready - Structure ready for Mindset, Posture, and Energy Mastery pillars

File Organization Conventions

app/
├── pages/
│   ├── pillars/                    # 🎯 All 5 pillars
│   │   ├── exercise/              # Pillar 4: Exercise
│   │   │   ├── index.tsx          # /pillars/exercise (library)
│   │   │   ├── [id].tsx           # /pillars/exercise/[id] (detail)
│   │   │   ├── [id]/
│   │   │   │   └── edit.tsx       # /pillars/exercise/[id]/edit
│   │   │   └── new.tsx            # /pillars/exercise/new
│   │   ├── nutrition/             # Pillar 2: Nutrition
│   │   │   └── index.tsx          # /pillars/nutrition (library)
│   │   ├── posture/               # Pillar 3: Posture (future)
│   │   │   └── index.tsx          # Coming soon
│   │   ├── mindset/               # Pillar 1: Mindset (future)
│   │   │   └── index.tsx          # Coming soon
│   │   └── energy/                # Pillar 5: Energy Mastery (future)
│   │       └── index.tsx          # Coming soon
│   ├── account/                    # User account features
│   │   ├── dashboard.tsx
│   │   ├── profile.tsx
│   │   └── sessions.tsx
│   ├── admin/                      # Admin features
│   │   └── index.tsx
│   ├── auth/                       # Authentication
│   │   ├── login.tsx
│   │   ├── register.tsx
│   │   └── ...
│   ├── assessments/                # Cross-pillar assessment system
│   ├── search.tsx                  # Global search
│   └── index.tsx                   # Homepage
│
├── pages/api/
│   ├── pillars/                    # 🎯 Pillar-specific APIs
│   │   ├── exercise/
│   │   │   ├── exercises/
│   │   │   ├── muscle-groups/
│   │   │   ├── equipment/
│   │   │   ├── categories/
│   │   │   ├── checkpoints/
│   │   │   └── progressions/
│   │   └── nutrition/
│   │       ├── foods/
│   │       ├── nutrients/
│   │       ├── categories/
│   │       └── health-conditions/
│   ├── assessments/                # Assessment APIs
│   ├── auth/                       # Authentication APIs
│   ├── session/                    # Session management
│   └── user/                       # User management
│
├── components/
│   ├── pillars/                    # 🎯 Pillar-specific components
│   │   ├── exercise/
│   │   │   ├── index.ts           # Barrel export
│   │   │   ├── ExerciseLibrary.tsx
│   │   │   ├── ExerciseForm.tsx
│   │   │   ├── ExerciseCard.tsx
│   │   │   └── ExerciseModal.tsx
│   │   ├── nutrition/
│   │   │   ├── index.ts
│   │   │   ├── NutritionLibrary.tsx
│   │   │   ├── FoodCard.tsx
│   │   │   └── NutrientModal.tsx
│   │   ├── posture/               # Future
│   │   ├── mindset/               # Future
│   │   └── energy/                # Future
│   ├── assessments/                # Assessment components
│   ├── auth/                       # Auth components
│   ├── layouts/                    # Layout components
│   ├── sessions/                   # Session components
│   └── shared/                     # Truly shared UI components
│
└── styles/
    ├── pillars/                    # 🎯 Pillar-specific styles
    │   ├── exercise/
    │   │   ├── _exercise-library.scss
    │   │   ├── _exercise-details.scss
    │   │   └── _exercise-form.scss
    │   ├── nutrition/
    │   │   └── _nutrition-library.scss
    │   ├── posture/               # Future
    │   ├── mindset/               # Future
    │   └── energy/                # Future
    ├── assessments/
    ├── dashboard/
    └── main.scss

URL Structure

Pillar Routes: - /pillars/exercise - Exercise library - /pillars/exercise/[id] - Exercise detail - /pillars/exercise/[id]/edit - Edit exercise - /pillars/exercise/new - Create new exercise - /pillars/nutrition - Nutrition library - /pillars/posture - Posture (coming soon) - /pillars/mindset - Mindset (coming soon) - /pillars/energy - Energy Mastery (coming soon)

System Routes: - /account/* - User account features - /admin/* - Admin features - /auth/* - Authentication - /assessments/* - Cross-pillar assessments - /search - Global search

Adding New Pillar Features

When adding features to a pillar:

Pages: Add to /pages/pillars/[pillar-name]/
API: Add to /pages/api/pillars/[pillar-name]/
Components: Add to /components/pillars/[pillar-name]/
Styles: Add to /styles/pillars/[pillar-name]/
Export: Update the barrel export in each component directory

Example: Adding a new exercise feature

# Page
app/pages/pillars/exercise/workout-plans.tsx

# API
app/pages/api/pillars/exercise/workout-plans/index.ts

# Component
app/components/pillars/exercise/WorkoutPlanCard.tsx

# Style
app/styles/pillars/exercise/_workout-plans.scss

Cross-Pillar Features

Features that span multiple pillars (like Assessments) remain at the root level: - /pages/assessments/ - /pages/api/assessments/ - /components/assessments/

Authentication & Session System

🎯 Purpose

Secure user authentication with cross-device session management, device fingerprinting, and concurrent session control.

📄 Pages

Authentication Pages (`/auth/*`)

Page	Route	Description
`pages/auth/login.tsx`	`/auth/login`	User login with credentials or Google OAuth
`pages/auth/register.tsx`	`/auth/register`	New user registration
`pages/auth/forgot-password.tsx`	`/auth/forgot-password`	Request password reset
`pages/auth/reset-password.tsx`	`/auth/reset-password`	Complete password reset
`pages/auth/verify-email.tsx`	`/auth/verify-email`	Email verification after registration
`pages/auth/resend-verification.tsx`	`/auth/resend-verification`	Resend verification email

Account Pages (`/account/*`)

Page	Route	Description
`pages/account/dashboard.tsx`	`/account/dashboard`	User account dashboard
`pages/account/profile.tsx`	`/account/profile`	User profile management
`pages/account/sessions.tsx`	`/account/sessions`	Manage active sessions

Admin Pages (`/admin/*`)

Page	Route	Description
`pages/admin/index.tsx`	`/admin`	Admin dashboard
`pages/admin/users.tsx`	`/admin/users`	User management (planned)
`pages/admin/analytics.tsx`	`/admin/analytics`	Platform analytics (planned)

🔌 API Endpoints

Endpoint	Method	Description
`/api/auth/[...nextauth]`	ALL	NextAuth authentication handler
`/api/auth/me`	GET	Get current user session
`/api/auth/register`	POST	Register new user
`/api/auth/login`	POST	User login
`/api/auth/logout`	POST	User logout
`/api/auth/forgot-password`	POST	Request password reset
`/api/auth/reset-password`	POST	Reset password with token
`/api/auth/verify-email`	POST	Verify email address
`/api/auth/resend-verification`	POST	Resend verification email
`/api/auth/sessions`	GET/DELETE	List/revoke user sessions
`/api/session/check`	GET	Check session validity
`/api/session/cross-device-check`	POST	Validate cross-device session
`/api/session/list`	GET	List all user sessions
`/api/session/cleanup`	POST	Clean expired sessions
`/api/session/limits`	GET	Get session limits by tier

🧩 Components

All components are organized by feature in dedicated directories for better maintainability:

components/
├── ComingSoon.tsx                   # Coming soon placeholder
├── Welcome.tsx                      # Welcome component
│
├── auth/                            # 📁 Authentication components
│   ├── index.ts                    # Barrel export
│   ├── LoginForm.tsx               # Login form with FingerprintJS
│   ├── RegisterForm.tsx            # Registration form
│   ├── ForgotPasswordForm.tsx      # Password reset request
│   └── ResetPasswordForm.tsx       # Password reset completion
│
├── layouts/                         # 📁 Layout components
│   ├── index.ts                    # Barrel export
│   ├── Layout.tsx                  # Base page layout
│   ├── AuthLayout.tsx              # Authentication page layout
│   ├── UnifiedHeader.tsx           # Main site header
│   └── Header.tsx                  # Alternate header
│
└── sessions/                        # 📁 Session management components
    ├── index.ts                    # Barrel export for clean imports
    │
    ├── Core Session Components
    ├── SessionActivityTracker.tsx   # Tracks session activity/heartbeat
    ├── SessionManagement.tsx        # Full session management dashboard
    ├── SessionManagementProvider.tsx # Context provider for session state
    ├── SessionNotification.tsx      # Session alerts and notifications
    ├── SessionNotification.module.css # Notification styles
    ├── SessionProvider.tsx          # Custom session provider
    ├── SessionStatus.tsx            # Current session status indicator
    ├── SessionTestingDashboard.tsx  # Dev testing interface
    │
    └── Session UI Components
        ├── SessionManager.tsx       # Session list and management UI
        ├── SessionCard.tsx          # Individual session card display
        ├── SessionWarningBanner.tsx # Session expiration warnings
        ├── SessionLimitModal.tsx    # Session limit reached modal
        ├── SessionStatusWidget.tsx  # Compact status display widget
        └── SessionDashboardWidget.tsx # Dashboard widget for sessions

Import Patterns:

// Authentication components
import { LoginForm, RegisterForm } from '@/components/auth';

// Layout components
import { UnifiedHeader, AuthLayout } from '@/components/layouts';

// Session components
import { 
  SessionStatus, 
  SessionManager, 
  SessionTestingDashboard 
} from '@/components/sessions';

// Or from main components index
import { LoginForm, UnifiedHeader, SessionStatus } from '@/components';

📚 Libraries & Utilities

Session logic (non-UI) remains in lib for separation of concerns:

lib/
├── auth.ts                          # NextAuth configuration
├── session/
│   ├── index.ts                    # Session exports (types, functions, hooks)
│   ├── core.ts                     # Session CRUD operations
│   ├── hooks.tsx                   # useCustomSession, CustomSessionProvider
│   ├── enforcement.ts              # Session limit enforcement
│   ├── limitEnforcement.ts         # Tier-based limit checking
│   ├── tracking.ts                 # Session activity tracking
│   ├── middleware.ts               # Session middleware
│   └── middlewareTracking.ts       # Middleware for tracking
└── db.ts                           # PostgreSQL connection pool

Architecture Decision: - Components: UI components in /components/sessions/ (React, JSX, visual) - Libraries: Business logic in /lib/session/ (functions, hooks, utilities) - Clear Separation: UI rendering vs data/logic processing

🗄️ Database Tables

users - User accounts (email, password_hash, role, session_generation)
user_sessions - Active sessions (session_token, device_fingerprint, expires_at, session_generation)

🔑 Key Features

Device Fingerprinting: FingerprintJS for browser identification
Cross-Device Control: Prevent concurrent sessions on same device type
Session Generation: Invalidate all sessions when security event occurs
Sliding Expiration: 30-minute inactive timeout
OAuth Support: Google authentication
Role-Based Access: User/Admin roles

🔄 Session System Flow

Complete Authentication & Session Creation Flow

┌─────────────────────────────────────────────────────────────────────┐
│ 1. USER INITIATES LOGIN                                             │
├─────────────────────────────────────────────────────────────────────┤
│ • User clicks "Sign in with Google" or enters credentials           │
│ • Browser: pages/login.tsx OR components/LoginForm.tsx              │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 2. NEXTAUTH AUTHENTICATION                                           │
├─────────────────────────────────────────────────────────────────────┤
│ • NextAuth handles OAuth flow with Google                            │
│ • Server: /api/auth/[...nextauth] (lib/auth.ts)                    │
│ • Validates user credentials                                         │
│ • Creates/updates user in database (users table)                    │
│ • Generates JWT token                                                │
│ • Sets NextAuth session cookies:                                     │
│   - __Secure-next-auth.session-token                                │
│   - __Host-next-auth.csrf-token                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 3. REDIRECT TO DASHBOARD                                             │
├─────────────────────────────────────────────────────────────────────┤
│ • User redirected to /dashboard                                      │
│ • NextAuth session active, but no database session yet               │
│ • Dashboard renders with UnifiedHeader component                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 4. DEVICE FINGERPRINT GENERATION                                     │
├─────────────────────────────────────────────────────────────────────┤
│ • UnifiedHeader detects authentication (isAuthenticated = true)      │
│ • Waits 2 seconds for NextAuth session to stabilize                 │
│ • Calls: initializeCrossDeviceEnforcement()                         │
│                                                                       │
│ Flow in lib/crossDeviceEnforcement.ts:                              │
│ ├── detectFromClient() in lib/unifiedDeviceDetection.ts            │
│ ├── deviceDetector.detectDevice() in lib/deviceDetection.ts        │
│ └── generateDeviceFingerprint()                                     │
│     • Uses browser attributes:                                       │
│       - User agent, screen size, pixel depth                         │
│       - Language, platform, timezone                                 │
│       - Cookie enabled, DNT setting                                  │
│     • Generates hash (e.g., "ak9lj4")                               │
│     • Stores in localStorage as 'deviceInfo':                       │
│       {                                                              │
│         sessionType: 'desktop',                                      │
│         deviceFingerprint: 'ak9lj4',                                │
│         deviceName: 'Chrome on macOS'                               │
│       }                                                              │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 5. DATABASE SESSION CREATION                                         │
├─────────────────────────────────────────────────────────────────────┤
│ • UnifiedHeader reads deviceInfo from localStorage                   │
│ • Calls: /api/auth/me with header:                                  │
│   X-Device-Fingerprint: ak9lj4                                      │
│                                                                       │
│ Flow in /api/auth/me:                                               │
│ ├── Validates NextAuth JWT token (getToken())                       │
│ ├── Checks for existing session with session_token cookie           │
│ ├── If no existing session OR different user:                       │
│ │   ├── Extracts device fingerprint from X-Device-Fingerprint header│
│ │   ├── Calls createSession() from lib/session/core.ts             │
│ │   └── Creates record in user_sessions table:                      │
│ │       {                                                            │
│ │         id: uuid,                                                  │
│ │         user_id: '929151dd-6983-4134-9603-0177ccc14c9a',         │
│ │         session_token: 'OQxEwgLhea...',  (random secure token)   │
│ │         device_fingerprint: 'ak9lj4',    (from header)           │
│ │         session_type: 'desktop',         (detected server-side)   │
│ │         session_generation: 1,                                     │
│ │         ip_address: '64.225.9.200',                               │
│ │         user_agent: 'Mozilla/5.0...',                             │
│ │         browser: 'Chrome',                                         │
│ │         os: 'macOS',                                               │
│ │         device: 'Desktop',                                         │
│ │         expires_at: NOW() + 30 days,                              │
│ │         last_activity_at: NOW(),                                   │
│ │         is_active: true                                            │
│ │       }                                                            │
│ └── Sets session_token cookie (HttpOnly, 30-day expiry)             │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 6. CROSS-DEVICE ENFORCEMENT INITIALIZATION                           │
├─────────────────────────────────────────────────────────────────────┤
│ • After session creation, UnifiedHeader continues initialization     │
│ • Cross-device enforcement starts polling                            │
│ • First validation check runs immediately                            │
│                                                                       │
│ Flow in lib/crossDeviceEnforcement.ts:                              │
│ • startEnforcement() sets up interval polling                        │
│ • validateSession() calls /api/session/cross-device-check           │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 7. CROSS-DEVICE SESSION VALIDATION                                   │
├─────────────────────────────────────────────────────────────────────┤
│ POST /api/session/cross-device-check                                 │
│ Body: {                                                              │
│   sessionType: 'desktop',                                            │
│   deviceFingerprint: 'ak9lj4',                                      │
│   deviceName: 'Chrome on macOS',                                     │
│   enforcementConfig: { shouldEnforce: true, ... }                   │
│ }                                                                    │
│                                                                       │
│ Server validates session:                                            │
│ 1. Verify NextAuth session (getServerSession)                       │
│ 2. Check if enforcement enabled for session type                     │
│ 3. Query database for matching session:                             │
│    SELECT * FROM user_sessions                                       │
│    WHERE user_id = $1                                                │
│    AND (device_fingerprint = $2                                      │
│         OR device_fingerprint LIKE '%' || $2 || '%')                │
│    AND is_active = true                                              │
│    AND expires_at > NOW()                                            │
│                                                                       │
│ 4. If session found:                                                 │
│    ├── Check session_generation matches user's current generation    │
│    ├── Call sessionLimitEnforcer.checkSessionLimit()                │
│    │   ├── Get user's tier and session limits                       │
│    │   ├── Count active sessions by type                            │
│    │   ├── Check if under limit (e.g., 1 desktop session allowed)   │
│    │   └── Return { allowed: true, currentUsage, limits }           │
│    ├── Update last_activity_at = NOW()                              │
│    └── Return { valid: true, needsLogout: false }                   │
│                                                                       │
│ 5. If session NOT found or invalid:                                  │
│    └── Return { valid: false, needsLogout: true,                    │
│                 reason: 'invalid_session' }                          │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 8. SESSION VALIDATION RESULT HANDLING                                │
├─────────────────────────────────────────────────────────────────────┤
│ Client receives validation result:                                   │
│                                                                       │
│ IF valid = true:                                                     │
│ • ✅ User stays logged in                                            │
│ • Validation continues polling every 60 seconds                      │
│ • Session activity timestamp updated on each validation              │
│                                                                       │
│ IF valid = false AND needsLogout = true:                            │
│ • ❌ Trigger cross-device logout                                     │
│ • Call /api/session/cross-device-signout                            │
│ • Set localStorage 'forceSignOut' to trigger logout on other tabs   │
│ • Redirect to /login                                                 │
└─────────────────────────────────────────────────────────────────────┘

Session Activity & Maintenance

Continuous Session Validation:

Every 60 seconds (while user is active):
├── Cross-device validation check runs
├── Updates last_activity_at timestamp
├── Checks session limits
├── Validates session generation
└── Returns session status

Session Expiration:

Sessions expire when:
├── expires_at timestamp passes (30 days from creation)
├── last_activity_at > 30 minutes ago (inactive timeout)
├── session_generation < user.session_generation (bulk invalidation)
└── is_active = false (manual termination)

Cleanup Process:

Automatic cleanup (scheduled job):
├── Delete sessions where expires_at < NOW()
├── Mark inactive sessions (last_activity_at > 30 min)
└── Remove orphaned sessions

Device Fingerprint Matching

Query Logic in cross-device-check.ts:

-- Matches both exact fingerprints and partial matches
WHERE device_fingerprint = 'ak9lj4'
   OR device_fingerprint LIKE '%ak9lj4%'

Why both conditions: - Exact match: Simple string comparison (fastest) - Partial match: Handles cases where fingerprint stored in JSON format - Fallback: Ensures compatibility with different storage formats

Session Limit Enforcement

Tier-Based Limits (from sessionLimitEnforcement.ts):

Free Tier:
├── desktop: 1 concurrent session
├── mobile_web: 1 concurrent session
├── mobile_app: 1 concurrent session
├── tablet: 1 concurrent session
├── incognito: unlimited (-1)
└── api_token: not allowed (0)

Pro Tier:
├── desktop: 3 concurrent sessions
├── mobile_web: 2 concurrent sessions
├── mobile_app: 2 concurrent sessions
└── ... (upgradeable)

Enforcement Logic:

On validation:
1. Get user's subscription tier
2. Get session limits for that tier
3. Count active sessions by type
4. If current sessions >= limit:
   ├── Block new sessions
   ├── Return list of oldest sessions
   └── Suggest actions (upgrade tier, terminate oldest)
5. If under limit:
   └── Allow session to continue

Session Generation System

Purpose: Bulk invalidation of all user sessions for security events

How it works:

User Record:
└── session_generation: 1 (current)

All Sessions:
└── session_generation: 1 (matches user)

Security Event (password change, suspicious activity):
├── Increment user.session_generation to 2
└── All old sessions (generation 1) now invalid

Next validation:
├── Compare session.session_generation (1) with user.session_generation (2)
├── Mismatch detected
└── Force logout, require re-authentication

Key Files & Their Roles

Session Creation: - /api/auth/me - Creates session with client fingerprint - lib/session/core.ts - createSession(), validateSession() - lib/deviceDetection.ts - Generates device fingerprint

Session Validation: - /api/session/cross-device-check - Validates sessions - lib/sessionLimitEnforcement.ts - Enforces tier limits - lib/crossDeviceEnforcement.ts - Client-side validation polling

Session Management: - components/UnifiedHeader.tsx - Orchestrates session flow - lib/auth.ts - NextAuth configuration - /api/auth/sessions - List/revoke sessions endpoint

Critical Implementation Details

Why fingerprint is generated BEFORE session creation: 1. Device detection must happen client-side (browser APIs) 2. Fingerprint stored in localStorage for consistency 3. Same fingerprint used for: - Session creation (via X-Device-Fingerprint header) - Session validation (from localStorage deviceInfo) 4. Prevents mismatch that would cause immediate logout

Why we removed server-side session creation: - JWT callback on server cannot access browser APIs - Server-generated fingerprints (timestamps) don’t match client - Would require client to update fingerprint after creation - Simpler to create session from client with correct fingerprint

Session Cookie vs Device Fingerprint: - session_token cookie: Identifies the session (secret, secure) - device_fingerprint: Identifies the device (persistent across sessions) - Both needed: Cookie for auth, fingerprint for cross-device control

Exercise Management System (Pillar 4)

🎯 Purpose

Comprehensive exercise library with muscle groups, equipment, categories, checkpoints, and progressions.

📄 Pages

Page	Route	Description
`pages/exercises/index.tsx`	`/exercises`	Exercise library with tabs for exercises, muscle groups, equipment, etc.
`pages/exercises/new.tsx`	`/exercises/new`	Create new exercise
`pages/exercises/[id].tsx`	`/exercises/[id]`	View exercise details
`pages/exercises/[id]/edit.tsx`	`/exercises/[id]/edit`	Edit existing exercise

🔌 API Endpoints

Exercises

Endpoint	Method	Description
`/api/exercises`	GET	List all exercises with filters
`/api/exercises`	POST	Create new exercise
`/api/exercises/[id]`	GET	Get exercise details
`/api/exercises/[id]`	PUT	Update exercise
`/api/exercises/[id]`	DELETE	Delete exercise
`/api/exercises/lookup-data`	GET	Get all lookup data (categories, muscle groups, etc.)
`/api/exercises/form-data`	GET	Get form dropdown data

Muscle Groups

Endpoint	Method	Description
`/api/exercises/muscle-groups`	GET	List muscle groups
`/api/exercises/muscle-groups`	POST	Create muscle group
`/api/exercises/muscle-groups`	PUT	Update muscle group
`/api/exercises/muscle-groups`	DELETE	Delete muscle group

Equipment

Endpoint	Method	Description
`/api/exercises/equipment`	GET	List equipment
`/api/exercises/equipment`	POST	Create equipment
`/api/exercises/equipment`	PUT	Update equipment
`/api/exercises/equipment`	DELETE	Delete equipment

Endpoint	Method	Description
`/api/exercises/categories`	GET	List categories
`/api/exercises/categories`	POST	Create category
`/api/exercises/categories`	PUT	Update category
`/api/exercises/categories`	DELETE	Delete category

Checkpoints

Endpoint	Method	Description
`/api/exercises/checkpoints`	GET	List checkpoints
`/api/exercises/checkpoints`	POST	Create checkpoint
`/api/exercises/checkpoints`	PUT	Update checkpoint
`/api/exercises/checkpoints`	DELETE	Delete checkpoint

Progressions

Endpoint	Method	Description
`/api/exercises/progressions`	GET	List progressions
`/api/exercises/progressions`	POST	Create progression
`/api/exercises/progressions`	PUT	Update progression
`/api/exercises/progressions`	DELETE	Delete progression

Supporting APIs

/api/exercises/anatomical-regions - Anatomical regions
/api/exercises/movement-roles - Movement roles (agonist, antagonist, etc.)
/api/exercises/muscle-fiber-types - Muscle fiber types

🧩 Components

components/exercises/
├── ExerciseLibrary.tsx              # Main library container with tabs
├── ExerciseForm.tsx                 # Exercise create/edit form
│
├── components/
│   ├── exercises/
│   │   ├── ExercisesTab.tsx        # Exercises list view
│   │   ├── ExerciseCard.tsx        # Exercise card display
│   │   └── ExerciseModal.tsx       # Exercise detail modal
│   │
│   ├── muscle-groups/
│   │   ├── MuscleGroupsTab.tsx     # Muscle groups manager
│   │   ├── MuscleGroupCard.tsx     # Muscle group card
│   │   └── (edit via EditItemModal)
│   │
│   ├── equipment/
│   │   ├── EquipmentTab.tsx        # Equipment manager
│   │   ├── EquipmentCard.tsx       # Equipment card
│   │   └── (edit via EditItemModal)
│   │
│   ├── categories/
│   │   ├── CategoriesTab.tsx       # Categories manager
│   │   ├── CategoryCard.tsx        # Category card
│   │   └── (edit via EditItemModal)
│   │
│   ├── checkpoints/
│   │   └── CheckpointsTab.tsx      # Checkpoints manager
│   │
│   └── shared/
│       ├── EditItemModal.tsx       # Generic edit modal
│       ├── LayoutToggle.tsx        # Grid/List view toggle
│       └── FilterSection.tsx       # Search and filters
│
└── utils/
    ├── index.ts                    # Utility functions
    ├── muscleGroupColors.ts        # Color coding for muscle groups
    └── exerciseHelpers.ts          # Exercise data helpers

🗄️ Database Tables

exercises - Exercise records
muscle_groups - Muscle group definitions
- Fields: id, name, simple_name, description, category, body_region, anatomical_location
equipment - Equipment items
categories - Exercise categories
checkpoints - Progression checkpoints
progressions - Exercise progressions
exercise_muscle_groups - Junction table (many-to-many)
exercise_equipment - Junction table (many-to-many)

🔑 Key Features

Tabbed Interface: Exercises, Muscle Groups, Equipment, Categories, Checkpoints, Progressions
Grid/List Views: Toggle between card grid and table list
Advanced Filtering: Search, category, difficulty, muscle group filters
Inline Editing: Edit muscle groups, equipment, categories directly in library
Modal Forms: Clean modal interface for editing
Image Upload: Support for exercise media
Relationships: Many-to-many relationships between exercises and muscle groups/equipment

📊 Muscle Group Fields

Name: Full muscle group name
Simple Name: Short reference name
Category: upper_body, lower_body, core
Body Region: arms, back, core, legs
Anatomical Location: anterior, posterior, lateral, medial, superior, inferior, deep, superficial
Functional Role: Description of muscle function (stored in description column)

Nutrition Management System (Pillar 2)

🎯 Purpose

Comprehensive nutrition database with foods, nutrients, health conditions, and dietary recommendations.

📄 Pages

Page	Route	Description
`pages/pillars/nutrition/index.tsx`	`/pillars/nutrition`	Nutrition library with tabs for foods, nutrients, etc.

🔌 API Endpoints

Foods

Endpoint	Method	Description
`/api/nutrition/foods`	GET	List foods with filters
`/api/nutrition/foods`	POST	Create new food
`/api/nutrition/foods/[id]`	GET	Get food details
`/api/nutrition/foods/[id]`	PUT	Update food
`/api/nutrition/foods/[id]`	DELETE	Delete food

Supporting Data

Endpoint	Description
`/api/nutrition/lookup-data`	Get all nutrition lookup data
`/api/nutrition/categories`	Food categories
`/api/nutrition/food-groups`	Food groups (grains, proteins, etc.)
`/api/nutrition/nutrients`	All nutrients
`/api/nutrition/vitamins-minerals`	Vitamins and minerals
`/api/nutrition/macronutrients`	Macronutrients (protein, carbs, fat)
`/api/nutrition/micronutrients`	Micronutrients
`/api/nutrition/health-conditions`	Health conditions
`/api/nutrition/organ-systems`	Organ systems
`/api/nutrition/special-diets`	Special diet tags
`/api/nutrition/tags`	General tags
`/api/nutrition/fruits-vegetables`	Fruits and vegetables
`/api/nutrition/herbs-spices`	Herbs and spices
`/api/nutrition/healing-foods`	Healing foods
`/api/nutrition/health-systems`	Body systems
`/api/nutrition/conditions`	Conditions/ailments

🧩 Components

components/pillars/nutrition/
├── NutritionLibrary.tsx             # Main nutrition library container
│
├── components/
│   ├── foods/
│   │   ├── FoodsTab.tsx            # Foods list view
│   │   └── FoodCard.tsx            # Food card display
│   │
│   ├── nutrients/
│   │   └── NutrientsTab.tsx        # Nutrients view
│   │
│   └── shared/
│       ├── EditItemModal.tsx       # Generic edit modal
│       ├── LayoutToggle.tsx        # Grid/List view toggle
│       └── FilterSection.tsx       # Search and filters
│
└── icons/
    └── nutrition-icon.tsx          # SVGR-generated nutrition icon (2248 lines)

🗄️ Database Tables

foods - Food items
nutrients - Nutrient definitions
vitamins_minerals - Vitamins and minerals
macronutrients - Protein, carbs, fats
micronutrients - Trace nutrients
food_categories - Food categories
food_groups - Food groups
health_conditions - Medical conditions
special_diets - Diet tags (vegan, keto, etc.)
food_nutrients - Junction table

🔑 Key Features

Comprehensive Database: Foods, nutrients, health relationships
Health Mapping: Link foods to health conditions and organ systems
Dietary Tags: Special diets, allergens, restrictions
Nutrient Profiles: Detailed macro/micro nutrient content
Search & Filter: Advanced filtering by category, diet, health condition
Custom Icon System: SVGR-converted SVG icons with preserved colors and styles

Standardized Library Headers

🎯 Purpose

All content library pages (Exercise, Nutrition, Assessments) now share a consistent header design pattern for improved user experience and visual consistency.

📐 Header Structure

Component Pattern:

<div className="exercise-library-header">
  <div className="exercise-library-header__content">
    <div className="exercise-library-header__text">
      <h2>Library Title</h2>
      <p>Library description text</p>
    </div>
    <div className="exercise-library-header__icon">
      {/* Icon component (150px-200px) */}
    </div>
  </div>
</div>

📚 Implementation Across Libraries

Exercise Library

Component: components/pillars/exercise/ExerciseLibrary.tsx
Icon: Custom SVG (inline)
Size: 150px
Title: “Exercise Content Library”
Description: “Comprehensive management system for all exercise-related content”

Nutrition Library

Component: components/pillars/nutrition/NutritionLibrary.tsx
Icon: SVGR-generated React component (nutrition-icon.tsx)
Size: 200x200px with viewBox=“0 0 300 300”
Title: “Nutrition Content Library”
Description: “Comprehensive management system for all nutrition-related content”
Special: 2248-line component with preserved colors from original SVG

Assessments Library

Component: components/assessments/AssessmentsLibrary.tsx
Icon: FileText from lucide-react
Size: 150px
Color: #34aadc (blue)
Title: “Client Assessments”
Description: “Create, manage, and organize your assessment templates and forms”

🎨 Icon Implementation Methods

Method 1: SVGR Tool (Nutrition Icon)

# Install SVGR CLI
npm install --save-dev @svgr/cli

# Convert SVG to React component
npx @svgr/cli --typescript \
  --out-dir components/icons \
  --filename-case kebab \
  public/nutrition-icon.svg

Benefits of SVGR: - ✅ Preserves all internal <style> tags as inline style props - ✅ Converts CSS classes to proper React attributes - ✅ Maintains all colors and styling from original SVG - ✅ TypeScript-compatible with SVGProps interface - ✅ No CSS scoping conflicts - ✅ Proper JSX attribute conversion (xmlns:xlink → xmlnsXlink)

Method 2: Inline SVG (Exercise Icon)

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  {/* SVG paths */}
</svg>

Method 3: Icon Library (Assessments Icon)

import { FileText } from 'lucide-react';

<FileText size={150} strokeWidth={1.5} style={{ color: '#34aadc' }} />

🔧 CSS Classes

Shared Styles:

.exercise-library-header {
  // Header container styles
  
  &__content {
    // Flex container for text and icon
    display: flex;
    justify-content: space-between;
    align-items: center;
  }
  
  &__text {
    // Text content area
    h2 { /* Title styles */ }
    p { /* Description styles */ }
  }
  
  &__icon {
    // Icon container
    width: 200px;
    height: 200px;
    display: flex;
    align-items: center;
    justify-content: center;
  }
}

Location: Styles compiled in .next/static/css/859288ddadee3626.css

📦 Package Dependencies

{
  "devDependencies": {
    "@svgr/cli": "^8.1.0"
  },
  "dependencies": {
    "lucide-react": "^0.263.1"
  }
}

🔄 Migration History

November 26, 2025 - Header Standardization: 1. Identified inconsistent header layouts across libraries 2. Standardized all three libraries to use exercise-library-header class structure 3. Implemented SVGR tool for complex SVG with internal styles (nutrition icon) 4. Updated AssessmentsLibrary.tsx to match header pattern 5. Fixed file naming issue (AssessmentsLibrary vs AssessmentLibrary) 6. All libraries now display consistent headers with proper icons and spacing

Key Learnings: - SVGR is superior to dangerouslySetInnerHTML for complex SVGs - Inline styles (from SVGR) prevent CSS scoping issues - Browser cache must be cleared after structural changes - Component file naming must match imports exactly

Assessment System

🎯 Purpose

Create, manage, and complete health assessments with scoring and results analysis.

📄 Pages

Page	Route	Description
`pages/assessments/index.tsx`	`/assessments`	Assessment library (private)
`pages/assessments/create.tsx`	`/assessments/create`	Create new assessment
`pages/assessments/[id]/edit.tsx`	`/assessments/[id]/edit`	Edit assessment
`pages/assessments/[id]/take.tsx`	`/assessments/[id]/take`	Take assessment (public)
`pages/assessments/my/index.tsx`	`/assessments/my`	User’s assessments
`pages/assessments/public.tsx`	`/assessments/public`	Public assessments list
`pages/assessments/results/[responseId].tsx`	`/assessments/results/[responseId]`	View assessment results

🔌 API Endpoints

Assessments

Endpoint	Method	Description
`/api/assessments`	GET	List assessments
`/api/assessments`	POST	Create assessment
`/api/assessments/[id]`	GET	Get assessment details
`/api/assessments/[id]`	PUT	Update assessment
`/api/assessments/[id]`	DELETE	Delete assessment
`/api/assessments/[id]/clone`	POST	Clone assessment
`/api/assessments/[id]/public`	GET	Get public assessment
`/api/assessments/my-assessments`	GET	User’s assessments
`/api/assessments/public`	GET	Public assessments

Questions & Responses

Endpoint	Method	Description
`/api/assessments/[id]/questions`	GET/POST	Manage questions
`/api/assessments/questions/[questionId]`	PUT/DELETE	Update/delete question
`/api/assessments/[id]/responses`	POST	Submit assessment response
`/api/assessments/responses/[responseId]`	GET	Get response details

Supporting Data

Endpoint	Description
`/api/assessments/lookup-data`	Get categories and option sets
`/api/assessments/categories`	Assessment categories
`/api/assessments/option-sets`	Predefined answer sets
`/api/assessments/templates`	Assessment templates

🧩 Components

components/assessments/
├── AssessmentsLibrary.tsx           # Main assessments library
├── EditAssessmentForm.tsx           # Assessment create/edit form
│
└── components/
    ├── AssessmentCard.tsx          # Assessment preview card
    ├── QuestionBuilder.tsx         # Question creation interface
    └── ResultsDisplay.tsx          # Results visualization

🗄️ Database Tables

assessments - Assessment definitions
assessment_questions - Questions
assessment_option_sets - Predefined answer options
assessment_responses - User responses
assessment_answers - Individual answers
assessment_categories - Assessment categories

🔑 Key Features

Question Types: Multiple choice, scale, text, etc.
Scoring System: Automated scoring and results
Public/Private: Share assessments publicly or keep private
Templates: Reusable assessment templates
Response Tracking: Track user responses and history
Results Analysis: Detailed results breakdown

Dashboard & User Interface

🎯 Purpose

Unified dashboard and navigation for all application features.

📄 Pages

Page	Route	Description
`pages/index.tsx`	`/`	Public landing page (Coming Soon)
`pages/account/dashboard.tsx`	`/account/dashboard`	Main user dashboard
`pages/admin/index.tsx`	`/admin`	Admin dashboard
`pages/pricing.tsx`	`/pricing`	Pricing tiers page
`pages/workout-builder.tsx`	`/workout-builder`	Workout builder tool
`pages/search.tsx`	`/search`	Global search across platform

🔌 API Endpoints

User & Subscription

Endpoint	Description
`/api/tiers`	Subscription tiers
`/api/user/subscription`	User subscription status
`/api/user/usage`	User usage statistics

Search

Endpoint	Method	Description
`/api/search/global`	GET	Global search across all platform content
`/api/search/exercises`	GET	Search exercises specifically
`/api/search/nutrition`	GET	Search nutrition/food items
`/api/search/assessments`	GET	Search assessments

🧩 Components

Layouts

components/
├── Layout.tsx                       # Base layout wrapper
├── AuthLayout.tsx                   # Authentication page layout
│
└── dashboard/
    ├── DashboardLayout.tsx         # Main dashboard layout
    ├── DashboardSidebar.tsx        # Navigation sidebar
    ├── DashboardHeader.tsx         # Dashboard header
    └── DashboardContent.tsx        # Content wrapper

components/
├── UnifiedHeader.tsx                # Site-wide header
├── Navigation.tsx                   # Main navigation
└── footer/
    └── Footer.tsx                  # Site footer

Dashboard Widgets

components/dashboard/
├── StatsCard.tsx                    # Statistics display cards
├── QuickActions.tsx                 # Quick action buttons
├── RecentActivity.tsx               # Recent activity feed
└── WelcomeCard.tsx                  # Welcome/greeting card

🔑 Key Features

Responsive Design: Mobile, tablet, desktop layouts
Sidebar Navigation: Collapsible sidebar with all features
Session Indicators: Session status always visible
Role-Based UI: Different views for user/admin
Quick Actions: Fast access to common tasks

Shared Components & Utilities

🧩 Shared Form Components

components/shared/
├── CleanForm.tsx                    # Form components library
│   ├── CleanFormField              # Form field wrapper
│   ├── CleanInput                  # Styled input
│   ├── CleanTextarea               # Styled textarea
│   ├── CleanSelect                 # Styled select dropdown
│   └── CleanButton                 # Styled button
│
├── CleanModal.tsx                   # Modal component
└── EditItemModal.tsx                # Generic edit modal

📚 Utility Libraries

lib/
├── db.ts                           # PostgreSQL connection pool
├── api-service.ts                  # Frontend API client
├── text-utils.ts                   # Text formatting utilities
├── date-utils.ts                   # Date formatting utilities
├── validation.ts                   # Form validation
└── constants.ts                    # Application constants

🎨 Styles

styles/
├── main.scss                       # Main stylesheet
├── _pricing.scss                   # Pricing page styles
├── assessment-take.css             # Assessment styles
├── assessment-results.css          # Results styles
├── assessment-medical-history.scss # Medical history styles
└── nutrition-library.scss          # Nutrition library styles

🔑 Shared Utilities

API Service: Centralized API client with error handling
Text Utils: capitalizeWords, formatName, slugify
Date Utils: formatDate, timeAgo, dateRange
Validation: Email, password, form validation rules
Constants: App-wide constants and enums

Database Schema

Core Tables

Users & Authentication

users (
  id UUID PRIMARY KEY,
  email VARCHAR UNIQUE,
  password_hash VARCHAR,
  first_name VARCHAR,
  last_name VARCHAR,
  role VARCHAR,  -- 'user' | 'admin'
  session_generation INTEGER,  -- Invalidate all sessions
  email_verified BOOLEAN,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

user_sessions (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users,
  session_token VARCHAR UNIQUE,
  device_fingerprint VARCHAR,
  session_generation INTEGER,
  session_type VARCHAR,  -- 'desktop' | 'mobile_web' | 'tablet'
  ip_address VARCHAR,
  user_agent TEXT,
  browser VARCHAR,
  os VARCHAR,
  device VARCHAR,
  location VARCHAR,
  expires_at TIMESTAMP,
  last_activity_at TIMESTAMP,
  is_active BOOLEAN,
  created_at TIMESTAMP
)

Exercises

exercises (
  id SERIAL PRIMARY KEY,
  name VARCHAR,
  description TEXT,
  category_id INTEGER,
  difficulty VARCHAR,
  instructions TEXT,
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  is_active BOOLEAN
)

muscle_groups (
  id SERIAL PRIMARY KEY,
  name VARCHAR,
  simple_name VARCHAR,
  description TEXT,  -- Used for "Functional Role"
  category VARCHAR,  -- 'upper_body' | 'lower_body' | 'core'
  body_region VARCHAR,  -- 'arms' | 'back' | 'core' | 'legs'
  anatomical_location VARCHAR,  -- 'anterior' | 'posterior' | etc.
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  is_active BOOLEAN
)

equipment (
  id SERIAL PRIMARY KEY,
  name VARCHAR,
  description TEXT,
  category VARCHAR,
  where_to_buy TEXT,
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  is_active BOOLEAN
)

exercise_muscle_groups (
  id SERIAL PRIMARY KEY,
  exercise_id INTEGER REFERENCES exercises,
  muscle_group_id INTEGER REFERENCES muscle_groups
)

exercise_equipment (
  id SERIAL PRIMARY KEY,
  exercise_id INTEGER REFERENCES exercises,
  equipment_id INTEGER REFERENCES equipment
)

Nutrition

foods (
  id SERIAL PRIMARY KEY,
  name VARCHAR,
  description TEXT,
  food_group_id INTEGER,
  category_id INTEGER,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

nutrients (
  id SERIAL PRIMARY KEY,
  name VARCHAR,
  type VARCHAR,  -- 'vitamin' | 'mineral' | 'macro' | 'micro'
  description TEXT
)

food_nutrients (
  id SERIAL PRIMARY KEY,
  food_id INTEGER REFERENCES foods,
  nutrient_id INTEGER REFERENCES nutrients,
  amount DECIMAL,
  unit VARCHAR
)

Assessments

assessments (
  id SERIAL PRIMARY KEY,
  title VARCHAR,
  description TEXT,
  category_id INTEGER,
  is_public BOOLEAN,
  created_by UUID REFERENCES users,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

assessment_questions (
  id SERIAL PRIMARY KEY,
  assessment_id INTEGER REFERENCES assessments,
  question_text TEXT,
  question_type VARCHAR,
  order_index INTEGER,
  required BOOLEAN
)

assessment_responses (
  id SERIAL PRIMARY KEY,
  assessment_id INTEGER REFERENCES assessments,
  user_id UUID REFERENCES users,
  score INTEGER,
  completed_at TIMESTAMP,
  created_at TIMESTAMP
)

assessment_answers (
  id SERIAL PRIMARY KEY,
  response_id INTEGER REFERENCES assessment_responses,
  question_id INTEGER REFERENCES assessment_questions,
  answer_text TEXT,
  answer_value INTEGER
)

Naming Conventions

Tables: lowercase with underscores (muscle_groups, exercise_equipment)
Columns: snake_case (created_at, is_active, body_region)
Primary Keys: id (serial or uuid)
Foreign Keys: {table}_id (user_id, exercise_id)
Timestamps: created_at, updated_at
Booleans: is_active, is_public, email_verified

Technology Stack

Frontend

Framework: Next.js 15.5.6 (React)
Language: TypeScript
Styling: SCSS, CSS Modules, styled-jsx
State Management: React Hooks (useState, useEffect, useContext)
Forms: Custom form components (CleanForm)
Icons: Lucide React, SVGR-generated custom icons
SVG Processing: @svgr/cli (converts SVG to React components)
Device Fingerprinting: @fingerprintjs/fingerprintjs

Backend

Runtime: Node.js
Framework: Next.js API Routes
Authentication: NextAuth.js v4
Database: PostgreSQL
ORM/Client: node-postgres (pg)
Password Hashing: bcrypt
Session Management: Custom JWT + Database sessions

Infrastructure

Server: Linux (Ubuntu/Debian)
Process Manager: PM2
Web Server: Nginx (reverse proxy)
Database: PostgreSQL 12+
SSL: Let’s Encrypt

Development Tools

Package Manager: npm
Build Tool: Next.js built-in (Webpack)
Linting: ESLint
Type Checking: TypeScript

External Services

OAuth: Google OAuth 2.0
Email: (TBD - verification emails)

Key Architectural Patterns

1. Session Management Pattern

Client (Browser)
├── FingerprintJS generates device fingerprint
├── Stored in localStorage
└── Sent via X-Device-Fingerprint header

Server
├── NextAuth handles authentication
├── Custom session created in database
├── Device fingerprint stored with session
├── Cross-device enforcement checks
└── Session generation for bulk invalidation

2. Component Organization Pattern

Feature-Based Directory Structure:

components/
├── {feature}/                      # All components for a feature
│   ├── index.ts                   # Barrel export for clean imports
│   ├── {Feature}Main.tsx          # Main feature component
│   ├── {Feature}Card.tsx          # Card/item display
│   └── {Feature}Modal.tsx         # Feature-specific modal
│
└── shared/                        # Truly shared components
    ├── CleanForm.tsx
    ├── CleanModal.tsx
    └── EditItemModal.tsx

Benefits of Consolidation: - ✅ Single source of truth (no duplicate files) - ✅ Clean imports: import { Component } from '@/components/feature' - ✅ Easy to discover related components - ✅ Clear feature boundaries - ✅ Prevents scattered files across codebase

Consolidation History (Nov 2025):

Session Components (Nov 19, 2025)
- Before: 23 files across 3 locations (/components/, /components/sessions/, /lib/session/components/)
- After: 14 unified files in /components/sessions/
- Result: 30% fewer files, zero duplication
Auth Components (Nov 19, 2025)
- Before: 4 files scattered at root (/components/LoginForm.tsx, etc.)
- After: Organized in /components/auth/ with barrel export
- Result: Clean grouping of authentication logic
Layout Components (Nov 19, 2025)
- Before: 4 layout files mixed with root components
- After: Organized in /components/layouts/ with barrel export
- Result: Clear separation of structural components

Total Impact: - 📉 12 files removed from root /components/ directory - 📁 3 new organized feature directories created - 🎯 100% of components now follow feature-based structure - 🔄 All imports standardized with barrel exports

3. Component Architecture

Page (Route)
└── Layout Component (DashboardLayout/AuthLayout)
    └── Feature Component (ExerciseLibrary/NutritionLibrary)
        └── Tab Components (ExercisesTab/MuscleGroupsTab)
            └── Item Components (ExerciseCard/MuscleGroupCard)
                └── Shared Components (EditItemModal/CleanForm)

3. API Structure

/api/{feature}/{resource}/{action}

Examples:
- /api/exercises/muscle-groups (GET/POST/PUT/DELETE)
- /api/nutrition/foods/[id] (GET/PUT/DELETE)
- /api/assessments/[id]/questions (GET/POST)

4. Data Flow

User Action → Page Component → API Service → API Route → Database → Response → State Update → UI Update

5. Authentication Flow

Login → NextAuth → Database Session → Device Fingerprint → Cross-Device Check → Protected Route Access

Feature Relationships

Exercise ←→ Muscle Groups (Many-to-Many)

Each exercise can target multiple muscle groups
Each muscle group can be in multiple exercises
Junction table: exercise_muscle_groups

Exercise ←→ Equipment (Many-to-Many)

Each exercise can require multiple equipment items
Each equipment can be used in multiple exercises
Junction table: exercise_equipment

Food ←→ Nutrients (Many-to-Many)

Each food contains multiple nutrients
Each nutrient appears in multiple foods
Junction table: food_nutrients

Assessment ←→ Questions (One-to-Many)

Each assessment has multiple questions
Each question belongs to one assessment

User ←→ Sessions (One-to-Many)

Each user can have multiple active sessions
Each session belongs to one user
Controlled by session limits per device type

Security Features

Password Security
- bcrypt hashing
- Minimum complexity requirements
- Password reset with time-limited tokens
Session Security
- Device fingerprinting (FingerprintJS)
- Cross-device enforcement
- Session generation for bulk invalidation
- Sliding expiration (30 minutes)
- IP and user agent tracking
API Security
- Session validation on all protected routes
- CSRF protection (NextAuth)
- SQL injection prevention (parameterized queries)
- XSS prevention (React sanitization)
Access Control
- Role-based access (user/admin)
- Protected routes (useCustomSession)
- API endpoint authorization

Development Workflow

Running the Application

# Development
cd /var/www/training.train5d.com/app
npm run dev

# Production Build
npm run build

# Start Production
pm2 start ecosystem.config.js
pm2 restart training-frontend

Database Migrations

# Connect to PostgreSQL
psql -U train5d -d training_platform

# Run migration scripts
\i migrations/001_create_tables.sql

Adding a New Feature

Plan Feature Structure
- Identify components needed
- Design API endpoints
- Plan database schema changes

Create Database Tables (if needed)

-- migrations/xxx_create_feature_tables.sql
CREATE TABLE feature_items (
  id SERIAL PRIMARY KEY,
  name VARCHAR NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

Create Feature Directory

components/
└── feature-name/
    ├── index.ts              # Barrel export
    ├── FeatureMain.tsx       # Main component
    ├── FeatureCard.tsx       # Sub-components
    └── FeatureModal.tsx

Create API Routes in /pages/api/

pages/api/
└── feature-name/
    ├── index.ts              # List/Create
    ├── [id].ts               # Get/Update/Delete
    └── lookup-data.ts        # Supporting data

Create Page in /pages/

// pages/feature-name.tsx
import { FeatureMain } from '@/components/feature-name';

export default function FeaturePage() {
  return <FeatureMain />;
}

Update Barrel Exports

// components/feature-name/index.ts
export { default as FeatureMain } from './FeatureMain';
export { default as FeatureCard } from './FeatureCard';

// components/index.ts
export * from './feature-name';

Update Navigation in sidebar/header
- Add route to components/UnifiedHeader.tsx
- Add to components/dashboard/DashboardSidebar.tsx
Test Authentication and permissions
- Verify protected routes work
- Test role-based access
- Validate session handling

Build and Deploy

npm run build
pm2 restart training-frontend

Best Practices: - Keep all feature components in one directory - Use barrel exports for clean imports - Separate UI (components) from logic (lib) - Follow existing naming conventions - Document in APPLICATION_ARCHITECTURE.md

Future Pillar Implementation

Mindset (Pillar 1)

Status: Not yet implemented

Planned Features: - Journal entries with mood tracking - Goal setting and progress visualization - Habit formation and tracking - Daily reflections and gratitude practices - Cognitive behavioral tools - Mindfulness and meditation guides - Progress milestones and celebrations

Database Tables (Planned): - mindset_journal_entries - mindset_goals - mindset_habits - mindset_mood_logs - mindset_milestones - mindset_reflections

Integration Points: - Link goals to exercise and nutrition plans - Track mood patterns with energy levels - Connect habits to all other pillars - Behavioral insights from cross-pillar data

Posture (Pillar 3)

Status: Not yet implemented

Planned Features: - Posture assessments and screenings - Movement pattern analysis - Ergonomic workspace evaluations - Corrective exercise prescriptions - Progress tracking with photos/videos - Pain and discomfort logging - Mobility and flexibility tracking

Database Tables (Planned): - posture_assessments - posture_movement_patterns - posture_ergonomics - posture_corrections - posture_pain_logs - posture_mobility_tests

Integration Points: - Link to exercise corrective programs - Connect pain patterns to nutrition (inflammation) - Track energy impacts from posture improvements - Mindset connection for body awareness

Energy Mastery (Pillar 5)

Status: Not yet implemented (The Integrative Pillar)

Planned Features: - Sleep quality tracking and optimization - Recovery metrics and readiness scores - Stress management tools - Energy level logging throughout the day - Circadian rhythm optimization - HRV and biometric integration - Environmental factors (light, temperature) - Caffeine and supplement timing

Database Tables (Planned): - energy_sleep_logs - energy_recovery_metrics - energy_stress_logs - energy_daily_levels - energy_biometrics - energy_environmental_factors - energy_supplements

Integration Points: - Connects ALL pillars (mindset, nutrition, posture, exercise) - Sleep impacts everything: recovery, mood, performance, cravings - Energy patterns inform workout timing and intensity - Nutrition timing based on energy needs - Stress management through all modalities - The hub that ties everything together

Cross-Pillar Integration Features

Unified User Dashboard: - 5-pillar health score visualization - Daily check-ins across all pillars - Interconnection insights (e.g., “Poor sleep affected workout performance”) - Holistic progress tracking - AI-powered recommendations considering all pillars

Integration Tables (Planned): - user_pillar_scores - Daily scores for each pillar - pillar_connections - Track how pillars affect each other - cross_pillar_insights - AI-generated insights - holistic_recommendations - Recommendations considering all 5 pillars

See: Five Pillars Integration Guide for detailed implementation strategy.

Future Enhancements

Additional Planned Features

Workout Builder completion
Exercise video uploads
Nutrition meal planning with AI
Advanced progress tracking and analytics
Mobile app (React Native)
Social features (share workouts, support groups)
AI-powered holistic recommendations across all 5 pillars
Wearable device integrations (Oura, Whoop, Apple Watch)
Telehealth integrations

Technical Debt

Standardize API response formats
Add comprehensive error logging
Implement rate limiting
Add API documentation (Swagger)
Unit and integration tests
Performance monitoring
Database indexing optimization
Reorganize assessments by pillar

Support & Maintenance

Monitoring

PM2 process monitoring
Database connection pooling
Session cleanup cron jobs
Error logging

Backup Strategy

Daily database backups
Media file backups
Configuration backups

Performance Optimization

Database query optimization
Image optimization
Code splitting (Next.js automatic)
CDN for static assets (future)

Recent Architecture Changes

Route Reorganization (November 26, 2025)

Authentication Routes Consolidated: - Moved all authentication pages to /pages/auth/ directory - Removed duplicate/old auth pages from root - Benefits: Clear separation of concerns, easier to maintain, follows Next.js conventions

Before:

pages/
├── login.tsx
├── register.tsx
├── forgot-password.tsx
├── verify-email.tsx
├── resend-verification.tsx
├── auth/
│   ├── signin.tsx
│   └── reset-password.tsx

After:

pages/
└── auth/
    ├── login.tsx
    ├── register.tsx
    ├── forgot-password.tsx
    ├── reset-password.tsx
    ├── verify-email.tsx
    └── resend-verification.tsx

Account Pages Reorganized: - Created /pages/account/ directory for user account features - Moved dashboard and profile to account section - Provides clear namespace for user-specific features

Before:

pages/
├── dashboard.tsx
├── profile.tsx

After:

pages/
└── account/
    ├── dashboard.tsx
    ├── profile.tsx
    └── sessions.tsx

Admin Pages Structured: - Created /pages/admin/ directory for admin features - Moved admin dashboard to admin section - Prepared for future admin features (users, analytics, etc.)

Before:

pages/
└── admin.tsx

After:

pages/
└── admin/
    └── index.tsx

Search Feature Added: - New global search functionality - API endpoints for searching across all content types - Search page with unified search interface - Search components and styles added

New Files:

pages/
├── search.tsx                      # Global search page
└── api/
    └── search/
        ├── global.ts              # Search all content
        ├── exercises.ts           # Exercise-specific search
        ├── nutrition.ts           # Nutrition-specific search
        └── assessments.ts         # Assessment-specific search

styles/
└── search/
    └── search.scss                # Search page styles

Benefits of Reorganization: 1. Clearer Structure: Features grouped by purpose (auth, account, admin) 2. Better Scalability: Easy to add new features within each section 3. Improved Navigation: Users understand where they are in the app 4. Easier Maintenance: Related files are co-located 5. RESTful Conventions: Routes match industry standards 6. Future-Proof: Room for growth in each section

Migration Notes: - All authentication routes now use /auth/* prefix - Dashboard moved to /account/dashboard - Admin features now under /admin/* - Old route files deleted to prevent confusion - No database changes required - Session system remains unchanged

Last Updated: November 26, 2025

Train5D Application Architecture

Table of Contents

Overview

The 5 Pillars

1. Mindset 🧠

2. Nutrition 🥗

3. Posture 🧘

4. Exercise 💪

5. Energy Mastery ⚡

Core Philosophy

Directory Structure

Pillar-Based Organization

Why Pillar-Based Structure?

File Organization Conventions

URL Structure

Adding New Pillar Features

Cross-Pillar Features

Authentication & Session System

🎯 Purpose

📄 Pages

Authentication Pages (/auth/*)

Account Pages (/account/*)

Admin Pages (/admin/*)

🔌 API Endpoints

🧩 Components

📚 Libraries & Utilities

🗄️ Database Tables

🔑 Key Features

🔄 Session System Flow

Complete Authentication & Session Creation Flow

Session Activity & Maintenance

Device Fingerprint Matching

Session Limit Enforcement

Session Generation System

Key Files & Their Roles

Critical Implementation Details

Exercise Management System (Pillar 4)

🎯 Purpose

📄 Pages

🔌 API Endpoints

Exercises

Muscle Groups

Equipment

Categories

Checkpoints

Progressions

Supporting APIs

🧩 Components

🗄️ Database Tables

🔑 Key Features

📊 Muscle Group Fields

Nutrition Management System (Pillar 2)

🎯 Purpose

📄 Pages

🔌 API Endpoints

Foods

Supporting Data

🧩 Components

🗄️ Database Tables

🔑 Key Features

Standardized Library Headers

🎯 Purpose

📐 Header Structure

📚 Implementation Across Libraries

Exercise Library

Nutrition Library

Assessments Library

🎨 Icon Implementation Methods

🔧 CSS Classes

📦 Package Dependencies

🔄 Migration History

Assessment System

🎯 Purpose

📄 Pages

🔌 API Endpoints

Assessments

Questions & Responses

Supporting Data

🧩 Components

🗄️ Database Tables

Authentication Pages (`/auth/*`)

Account Pages (`/account/*`)

Admin Pages (`/admin/*`)