Documentation

# Clone and setup
git clone https://github.com/itigges22/movalab.git
cd movalab
./scripts/first-time-setup.sh  # or scripts\first-time-setup.bat on Windows
npm run dev

# Open http://localhost:3000
# Login: superadmin@test.local / Test1234!

# Check Node.js version (must be 18.17+)
node -v

# Check npm version
npm -v

# Check Docker is running (should list version, not error)
docker --version
docker ps  # Should show empty table, not "Cannot connect"

# Check Git version
git --version

# Optional: Check Supabase CLI (auto-installed via npx if not present)
npx supabase --version

# Optional: Login to Docker Hub (avoids rate limits)
docker login

# Step 1: Clone the repository
git clone https://github.com/itigges22/movalab.git
cd movalab

# Step 2: Run the setup script (macOS / Linux / Git Bash)
./scripts/first-time-setup.sh

# OR for Windows CMD / PowerShell:
scripts\first-time-setup.bat

# 1. Clone and enter directory
git clone https://github.com/itigges22/movalab.git
cd movalab

# 2. Install npm packages
npm install

# 3. Copy environment template
cp .env.example .env.local

# 4. Start Supabase (first run downloads images)
npx supabase start

# 5. Get the anon key (copy output to .env.local)
npx supabase status

# 6. Update .env.local with values from step 5:
# NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
# NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=<anon key from status>

# 7. Run database migrations
npx supabase db push

# 8. Seed test data
npx supabase db seed

# 9. Generate TypeScript types
npm run gen:types

# 10. Start development server
npm run dev

# First-time Setup
npm run docker:init       # Initialize Supabase project (runs supabase init)

# Daily Development
npm run docker:start      # Start Supabase services (wraps: npx supabase start)
npm run docker:stop       # Stop containers (preserves data)
npm run docker:status     # Check service health (wraps: npx supabase status)

# Database Management
npm run docker:reset      # Reset DB, re-run all migrations
npm run docker:seed       # Reset DB + seed test users
npm run docker:studio     # Open Supabase Studio at localhost:54323

# Troubleshooting
npm run docker:health     # Verify Docker setup is healthy
npm run docker:logs       # View container logs
npm run docker:clean      # Remove all containers and volumes (fresh start)

# Development Server
npm run dev              # Start on localhost:3000
npm run dev:local        # Start with local Supabase (docker:start + dev)
npm run dev:cloud        # Start with cloud Supabase (uses .env.local cloud keys)
npm run dev:clean        # Clean .next cache and start
npm run dev:fresh        # Kill port 3000, clean cache, start fresh

# Build & Production
npm run build            # Production build (catches type errors)
npm run start            # Start production server
npm run lint             # Run ESLint

# Types & Code Generation
npm run gen:types        # Regenerate Supabase TypeScript types

# Cleanup
npm run clean            # Clean .next and cache directories

# Schema & Migrations
npx supabase db pull            # Pull remote schema to local migrations
npx supabase db push            # Push local migrations to remote database
npx supabase db reset           # Reset local database and run all migrations
npx supabase db diff            # Show differences between local and remote schema

# Type Generation
npx supabase gen types typescript --local > src/types/supabase.ts
# Generates TypeScript types from your database schema

# Status & Info
npx supabase status             # Show local Supabase service status and keys
npx supabase start              # Start local Supabase (same as docker:start)
npx supabase stop               # Stop local Supabase (same as docker:stop)

# Remote Connection (for cloud Supabase)
npx supabase link --project-ref <project-id>  # Link to cloud project
npx supabase db pull --schema public          # Pull cloud schema locally

# 1. Check all Docker containers are running
docker ps
# Should show 6+ Supabase containers (db, auth, storage, etc.)

# 2. Verify Supabase is healthy
npm run docker:health
# Should report all services as healthy

# 3. Test database connection
npx supabase status
# Should show connection details and API keys

# 4. Verify app is running
curl http://localhost:3000
# Should return HTML (or open in browser)

# 5. Run build to catch any TypeScript errors
npm run build
# Should complete without errors

┌─────────────────────────────────────────────────────────────────────────────┐
│                             MOVALAB ARCHITECTURE                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                        PRESENTATION LAYER                           │    │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │    │
│  │  │ Server Components│  │ Client Components│  │   shadcn/ui     │     │    │
│  │  │ (Data Fetching) │  │ (Interactivity) │  │  (UI Library)   │     │    │
│  │  └─────────────────┘  └─────────────────┘  └─────────────────┘     │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                    │                                         │
│                                    ▼                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                          API LAYER                                   │    │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │    │
│  │  │  API Routes     │  │  Server Actions  │  │  Middleware     │     │    │
│  │  │  (83 endpoints) │  │  (Form handling) │  │  (Auth check)   │     │    │
│  │  └─────────────────┘  └─────────────────┘  └─────────────────┘     │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                    │                                         │
│                                    ▼                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                         SERVICE LAYER                                │    │
│  │  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐            │    │
│  │  │ Permission    │  │   Validation  │  │  Business     │            │    │
│  │  │ Checker       │  │   (Zod)       │  │  Logic (43)   │            │    │
│  │  └───────────────┘  └───────────────┘  └───────────────┘            │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                    │                                         │
│                                    ▼                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                          DATA LAYER                                  │    │
│  │  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐            │    │
│  │  │ Supabase      │  │  PostgreSQL   │  │  Row Level    │            │    │
│  │  │ Clients (3)   │  │  (33 tables)  │  │  Security     │            │    │
│  │  └───────────────┘  └───────────────┘  └───────────────┘            │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

movalab/
├── app/                              # Next.js App Router
│   ├── (auth)/                       # Auth routes (unprotected)
│   │   ├── login/                    # Login page
│   │   ├── register/                 # Registration page
│   │   └── forgot-password/          # Password reset
│   ├── (dashboard)/                  # Protected dashboard routes
│   │   ├── projects/                 # Project management
│   │   │   ├── [id]/                 # Project detail (dynamic route)
│   │   │   │   ├── page.tsx          # Project overview
│   │   │   │   ├── tasks/            # Task management
│   │   │   │   ├── timeline/         # Project timeline
│   │   │   │   └── settings/         # Project settings
│   │   │   └── new/                  # Create project
│   │   ├── accounts/                 # Client accounts
│   │   │   ├── [id]/                 # Account detail
│   │   │   │   ├── projects/         # Account projects
│   │   │   │   ├── members/          # Account members
│   │   │   │   └── kanban/           # Kanban configuration
│   │   ├── admin/                    # Admin panel
│   │   │   ├── roles/                # Role management + org chart
│   │   │   ├── users/                # User management
│   │   │   ├── departments/          # Department management
│   │   │   └── workflows/            # Workflow templates
│   │   ├── capacity/                 # Capacity planning
│   │   ├── time-entries/             # Time tracking
│   │   ├── workflows/                # Workflow builder (React Flow)
│   │   └── pipeline/                 # Project pipeline view
│   └── api/                          # API routes (83 endpoints)
│       ├── projects/                 # Project endpoints
│       ├── tasks/                    # Task endpoints
│       ├── accounts/                 # Account endpoints
│       ├── workflows/                # Workflow endpoints
│       ├── time-entries/             # Time tracking endpoints
│       ├── capacity/                 # Capacity endpoints
│       └── admin/                    # Admin endpoints
├── components/                       # React components (107 total)
│   ├── ui/                           # shadcn/ui base components (27)
│   ├── workflow-editor/              # React Flow workflow components
│   ├── org-chart/                    # Org chart components
│   ├── time-entries/                 # Time tracking components
│   ├── capacity/                     # Capacity components
│   └── [feature]/                    # Feature-specific components
├── lib/                              # Core libraries and services
│   ├── supabase.ts                   # Client-side Supabase (singleton)
│   ├── supabase-server.ts            # Server-side Supabase clients
│   ├── permissions.ts                # Permission enum (40 permissions)
│   ├── permission-checker.ts         # Hybrid permission engine
│   ├── rbac.ts                       # RBAC helper functions
│   ├── rbac-types.ts                 # TypeScript types
│   ├── auth.ts                       # Authentication utilities
│   ├── validation-schemas.ts         # Zod validation schemas
│   ├── debug-logger.ts               # Logging utilities
│   ├── config.ts                     # App configuration
│   ├── rate-limit.ts                 # Rate limiting
│   └── services/                     # Business logic services
│       ├── capacity-service.ts       # Capacity calculations
│       ├── time-entry-service.ts     # Time entry logic
│       └── availability-service.ts   # Availability management
├── lib/                              # Additional service files (43 total)
│   ├── account-service.ts            # Account CRUD + members
│   ├── assignment-service.ts         # Project/task assignments
│   ├── client-portal-service.ts      # Client portal features
│   ├── department-service.ts         # Department management
│   ├── form-service.ts               # Form templates + responses
│   ├── newsletter-service.ts         # Newsletter management
│   ├── organization-service.ts       # Org chart service
│   ├── project-issues-service.ts     # Project issue tracking
│   ├── role-management-service.ts    # Role CRUD
│   ├── workflow-service.ts           # Workflow template management
│   └── workflow-execution-service.ts # Workflow execution engine
├── supabase/
│   └── migrations/                   # Database migrations (5 files)
│       ├── 20250123000000_schema_base.sql     # Table definitions
│       ├── 20250123010000_functions_fixed.sql # Database functions
│       ├── 20250123020000_views.sql           # Views
│       ├── 20250123030000_rls_policies_fixed.sql # RLS policies
│       └── 20250123040000_triggers.sql        # Triggers
├── scripts/                          # Setup and utility scripts
│   ├── first-time-setup.sh           # Mac/Linux setup
│   ├── first-time-setup.bat          # Windows setup
│   └── seed-data.sql                 # Demo data
└── tests/                            # Test files
    └── e2e/                          # Playwright E2E tests

┌─────────────────────────────────────────────────────────────────────────────┐
│                        SUPABASE CLIENT PATTERNS                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  1. CLIENT COMPONENT (createClientSupabase)                                  │
│  ─────────────────────────────────────────                                   │
│  File: lib/supabase.ts                                                       │
│  Use in: Browser-side code, Client Components                                │
│  Auth: Uses browser cookies automatically                                    │
│                                                                              │
│  const supabase = createClientSupabase();                                    │
│  // Returns singleton instance in browser                                    │
│  // Returns null on server (SSR) - must use createServerSupabase instead     │
│                                                                              │
│  Key Features:                                                               │
│  - Singleton pattern (avoids multiple GoTrueClient instances)                │
│  - Auto session refresh on token expiry                                      │
│  - Auth state change listener for logout/refresh                             │
│                                                                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  2. SERVER COMPONENT (createServerSupabase)                                  │
│  ─────────────────────────────────────────                                   │
│  File: lib/supabase-server.ts                                                │
│  Use in: React Server Components (RSC), page.tsx data fetching               │
│  Auth: Uses cookies() from next/headers                                      │
│                                                                              │
│  const supabase = await createServerSupabase();                              │
│  // Async function - must await                                              │
│  // Uses cookies() which must be awaited in Next.js 15                       │
│                                                                              │
│  Key Features:                                                               │
│  - Reads auth cookies from request                                           │
│  - 30-second fetch timeout to prevent hanging                                │
│  - Safe cookie handling (catches errors in API routes)                       │
│                                                                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  3. API ROUTE (createApiSupabaseClient)                                      │
│  ──────────────────────────────────────                                      │
│  File: lib/supabase-server.ts                                                │
│  Use in: API routes (route.ts files), Route Handlers                         │
│  Auth: Parses cookies from request headers                                   │
│                                                                              │
│  export async function POST(request: NextRequest) {                          │
│    const supabase = createApiSupabaseClient(request);                        │
│    // REQUIRED: Pass request object for cookie parsing                       │
│    // Must pass this client to hasPermission() for proper RLS                │
│  }                                                                           │
│                                                                              │
│  CRITICAL: cookies() from next/headers CANNOT be used in Route Handlers      │
│  We must parse cookies from request.headers.get('cookie') instead            │
│                                                                              │
│  Key Features:                                                               │
│  - Parses cookies from request.headers and request.cookies                   │
│  - URL decodes cookie values                                                 │
│  - 30-second fetch timeout                                                   │
│  - ALWAYS pass to hasPermission() for correct RLS context                    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                        REQUEST LIFECYCLE (API ROUTE)                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  1. USER ACTION                                                              │
│     └── Click "Create Project" button                                        │
│                                                                              │
│  2. CLIENT COMPONENT                                                         │
│     └── fetch('/api/projects', { method: 'POST', body: JSON.stringify(...) })│
│                                                                              │
│  3. MIDDLEWARE (middleware.ts)                                               │
│     ├── Check auth cookies                                                   │
│     └── Redirect to /login if not authenticated                              │
│                                                                              │
│  4. API ROUTE (app/api/projects/route.ts)                                    │
│     ├── Create Supabase client: createApiSupabaseClient(request)             │
│     ├── Get authenticated user: supabase.auth.getUser()                      │
│     └── Parse request body: await request.json()                             │
│                                                                              │
│  5. VALIDATION (lib/validation-schemas.ts)                                   │
│     ├── validateRequestBody(createProjectSchema, body)                       │
│     └── Return 400 if validation fails                                       │
│                                                                              │
│  6. PERMISSION CHECK (lib/permission-checker.ts)                             │
│     ├── hasPermission(userProfile, Permission.MANAGE_PROJECTS, { accountId })│
│     ├── Layer 1: Superadmin bypass?                                          │
│     ├── Layer 2: Base permission check                                       │
│     ├── Layer 3: Override or context check                                   │
│     └── Return 403 if permission denied                                      │
│                                                                              │
│  7. SERVICE LAYER (lib/account-service.ts, etc.)                             │
│     ├── Execute business logic                                               │
│     ├── Call supabase.from('projects').insert(...)                           │
│     └── Handle side effects (notifications, audit log)                       │
│                                                                              │
│  8. DATABASE (Supabase PostgreSQL)                                           │
│     ├── RLS policy evaluation: auth.uid() checked                            │
│     ├── INSERT executed if RLS allows                                        │
│     └── Triggers fire (updated_at, etc.)                                     │
│                                                                              │
│  9. RESPONSE                                                                 │
│     ├── Service returns { success: true, project }                           │
│     ├── API route returns NextResponse.json({ project }, { status: 201 })    │
│     └── Client receives response, updates UI                                 │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Dynamic Department Membership Flow:

1. User is assigned to a project
   └── project_assignments.insert({ user_id, project_id, role_in_project })

2. User has a role (e.g., "Graphic Designer")
   └── user_roles.role_id → roles.id

3. Role belongs to a department (e.g., "Graphics")
   └── roles.department_id → departments.id

4. User is now "in" Graphics department
   └── Calculated at query time, not stored statically
   └── getUserDepartments(userProfile) returns ["Graphics"]

5. User removed from all Graphics projects
   └── No longer appears in Graphics department
   └── Capacity calculations update automatically

// Query to get user's current departments
SELECT DISTINCT d.name
FROM user_roles ur
JOIN roles r ON ur.role_id = r.id
JOIN departments d ON r.department_id = d.id
WHERE ur.user_id = :userId;

// This is why departments are "dynamic" - no explicit assignment table needed

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MOVALAB DATABASE SCHEMA                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐                │
│  │ auth.users   │────►│user_profiles │◄───►│  user_roles  │                │
│  └──────────────┘     └──────────────┘     └──────┬───────┘                │
│                              │                     │                        │
│                              ▼                     ▼                        │
│                       ┌──────────────┐     ┌──────────────┐                │
│                       │account_members│     │    roles     │                │
│                       └──────┬───────┘     └──────┬───────┘                │
│                              │                     │                        │
│                              ▼                     ▼                        │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐                │
│  │   accounts   │◄────│   projects   │────►│ departments  │                │
│  └──────────────┘     └──────┬───────┘     └──────────────┘                │
│                              │                                              │
│         ┌────────────────────┼────────────────────┐                        │
│         ▼                    ▼                    ▼                        │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐                │
│  │    tasks     │     │project_assign│     │ time_entries │                │
│  └──────┬───────┘     └──────────────┘     └──────────────┘                │
│         │                                                                   │
│         ▼                                                                   │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐                │
│  │task_week_    │     │clock_sessions│     │workflow_     │                │
│  │allocations   │     └──────────────┘     │instances     │                │
│  └──────────────┘                          └──────────────┘                │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

auth.users → user_profiles → user_roles, account_members, project_assignments, time_entries
accounts → projects → tasks → time_entries, task_week_allocations, task_dependencies
workflow_templates → workflow_nodes → workflow_connections
workflow_instances → workflow_history, workflow_active_steps

┌─────────────────────────────────────────────────────────────────────────────┐
│                    HYBRID PERMISSION SYSTEM (3 LAYERS)                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  LAYER 1: SUPERADMIN BYPASS                                                  │
│  ─────────────────────────                                                   │
│  Check: userProfile.is_superadmin === true                                   │
│         OR user has "Superadmin" system role                                 │
│  Result: ALLOW (skip all other checks)                                       │
│                                                                              │
│  LAYER 2: BASE PERMISSION CHECK                                              │
│  ────────────────────────────                                                │
│  Check: Does any of the user's roles have this permission set to TRUE?       │
│  Logic: OR across all roles (if ANY role has it, permission is granted)      │
│  Result: If FALSE → DENY immediately                                         │
│          If TRUE → Continue to Layer 3                                       │
│                                                                              │
│  LAYER 3: CONTEXT-AWARE CHECK (for resource-specific permissions)            │
│  ────────────────────────────────────────────────────────────────           │
│  a) Check OVERRIDE permissions first:                                        │
│     - VIEW_ALL_PROJECTS bypasses project assignment check                    │
│     - MANAGE_ALL_PROJECTS bypasses project assignment check                  │
│     - VIEW_ALL_DEPARTMENTS bypasses department membership check              │
│     - EXECUTE_ANY_WORKFLOW bypasses workflow node assignment                 │
│     If user has override → ALLOW                                             │
│                                                                              │
│  b) Check CONTEXT assignment:                                                │
│     - projectId: Is user assigned to this project?                           │
│     - accountId: Is user an account member or manager?                       │
│     - departmentId: Does user have a role in this department?                │
│     - workflowInstanceId: Is user assigned to current workflow node?         │
│     If context matches → ALLOW                                               │
│     If context doesn't match → DENY                                          │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

import { hasPermission, isSuperadmin } from '@/lib/rbac';
import { Permission } from '@/lib/permissions';

// ============================================
// EXAMPLE 1: Check permission without context
// ============================================
const canManageAccounts = await hasPermission(
  userProfile,
  Permission.MANAGE_ACCOUNTS,
  undefined,        // No context needed
  supabaseClient    // REQUIRED on server-side, optional on client
);

// ============================================
// EXAMPLE 2: Check permission WITH context
// ============================================
const canEditProject = await hasPermission(
  userProfile,
  Permission.MANAGE_PROJECTS,
  { projectId: project.id, accountId: project.account_id },  // Context
  supabaseClient
);
// This checks:
// 1. Is user superadmin? → ALLOW
// 2. Has MANAGE_ALL_PROJECTS? → ALLOW (override)
// 3. Has MANAGE_PROJECTS AND is assigned to this project? → ALLOW
// 4. Otherwise → DENY

// ============================================
// EXAMPLE 3: Check multiple permissions (ANY)
// ============================================
import { hasAnyPermission } from '@/lib/rbac';

const canAccessAdmin = await hasAnyPermission(
  userProfile,
  [Permission.MANAGE_USERS, Permission.MANAGE_USER_ROLES, Permission.MANAGE_ACCOUNTS],
  undefined,
  supabaseClient
);

// ============================================
// EXAMPLE 4: Check multiple permissions (ALL)
// ============================================
import { hasAllPermissions } from '@/lib/rbac';

const canFullyManageWorkflows = await hasAllPermissions(
  userProfile,
  [Permission.MANAGE_WORKFLOWS, Permission.EXECUTE_WORKFLOWS],
  undefined,
  supabaseClient
);

// ============================================
// EXAMPLE 5: Superadmin check (use sparingly)
// ============================================
if (isSuperadmin(userProfile)) {
  // Bypass all permission checks
  // Only use for truly admin-only features
}

// Override permission mappings in permission-checker.ts

const overridePermissions = {
  // Projects
  VIEW_PROJECTS:     → VIEW_ALL_PROJECTS
  MANAGE_PROJECTS:   → MANAGE_ALL_PROJECTS

  // Departments
  VIEW_DEPARTMENTS:    → VIEW_ALL_DEPARTMENTS
  MANAGE_DEPARTMENTS:  → VIEW_ALL_DEPARTMENTS

  // Accounts
  VIEW_ACCOUNTS:    → VIEW_ALL_ACCOUNTS
  MANAGE_ACCOUNTS:  → VIEW_ALL_ACCOUNTS

  // Updates
  VIEW_UPDATES:    → VIEW_ALL_UPDATES
  MANAGE_UPDATES:  → VIEW_ALL_UPDATES

  // Time Tracking
  VIEW_TIME_ENTRIES: → VIEW_ALL_TIME_ENTRIES
  EDIT_TIME_ENTRIES: → VIEW_ALL_TIME_ENTRIES
  MANAGE_TIME:       → VIEW_ALL_TIME_ENTRIES

  // Workflows
  MANAGE_WORKFLOWS:  → MANAGE_ALL_WORKFLOWS
  EXECUTE_WORKFLOWS: → [EXECUTE_ANY_WORKFLOW, MANAGE_ALL_WORKFLOWS]

  // Analytics (tiered)
  VIEW_ALL_DEPARTMENT_ANALYTICS: → [VIEW_ALL_ACCOUNT_ANALYTICS, VIEW_ALL_ANALYTICS]
  VIEW_ALL_ACCOUNT_ANALYTICS:    → VIEW_ALL_ANALYTICS

  // Capacity
  VIEW_TEAM_CAPACITY: → VIEW_ALL_CAPACITY
}

// Permission check logs include:
{
  permission: "MANAGE_PROJECTS",
  userId: "uuid",
  result: true,
  reason: "override_permission" | "base_permission" | "context_match" | "superadmin",
  duration: 12,  // milliseconds
  context: { projectId: "uuid", accountId: "uuid" },
  cached: true
}

// Common log reasons:
// "superadmin"       - User is superadmin (bypass)
// "no_base_permission" - User's roles don't have the permission
// "override_permission" - User has VIEW_ALL_* or similar override
// "context_match"    - Base permission + assigned to resource
// "no_context_match" - Has permission but not assigned to resource

INSERT INTO roles (name, level, permissions, department_id, description) VALUES (
  'Content Strategist',
  45,
  '{"view_projects": true, "edit_own_tasks": true, "view_accounts": true}'::jsonb,
  (SELECT id FROM departments WHERE name = 'Marketing'),
  'Creates and manages content strategy'
);

┌─────────────────────────────────────────────────────────────────────────────┐
│                           WORKFLOW ARCHITECTURE                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌────────────────────┐    ┌─────────────────────┐    ┌──────────────────┐  │
│  │ workflow_templates │───▶│   workflow_nodes    │───▶│workflow_connections│ │
│  │  (definitions)     │    │   (steps/stages)    │    │  (transitions)    │  │
│  └────────────────────┘    └─────────────────────┘    └──────────────────┘  │
│           │                                                                  │
│           ▼                                                                  │
│  ┌────────────────────┐    ┌─────────────────────┐    ┌──────────────────┐  │
│  │workflow_instances  │───▶│  workflow_history   │───▶│workflow_approvals │  │
│  │  (executions)      │    │ (transition log)    │    │ (decisions)       │  │
│  └────────────────────┘    └─────────────────────┘    └──────────────────┘  │
│           │                                                                  │
│           ▼                                                                  │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │                        SNAPSHOT SYSTEM                                  │ │
│  │  started_snapshot: Captured when workflow starts - workflow changes    │ │
│  │                    don't affect in-progress projects                   │ │
│  │  completed_snapshot: Captured at completion - preserves final state    │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                              │
│  SERVICE LAYERS:                                                             │
│  ├── workflow-service.ts: Template CRUD, node/connection management         │
│  └── workflow-execution-service.ts: Start, progress, complete workflows     │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                        WORKFLOW EXECUTION LIFECYCLE                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  1. START WORKFLOW (startWorkflowForProject)                                 │
│     ├── Validate template exists and is_active = true                        │
│     ├── Verify template has at least Start and End nodes                     │
│     ├── Create started_snapshot (nodes + connections frozen)                 │
│     ├── Create workflow_instance with status = 'active'                      │
│     ├── Link to project (projects.workflow_instance_id)                      │
│     ├── Create initial workflow_history entry                                │
│     ├── Create workflow_active_steps entry for first node                    │
│     └── assignProjectToNode() - add users via project_assignments            │
│                                                                              │
│  2. PROGRESS WORKFLOW (progressWorkflow)                                     │
│     ├── AUTHORIZATION CHECKS:                                                │
│     │   ├── Superadmin bypass (isUserSuperadmin)                            │
│     │   ├── Project assignment check (isUserAssignedToProject)              │
│     │   └── Role/department validation based on node.entity_id             │
│     ├── Determine next node based on:                                        │
│     │   ├── Normal: findNextNode() - follows connection                     │
│     │   ├── Approval: findDecisionBasedNextNode() - uses decision           │
│     │   └── Conditional: findConditionalNextNode() - evaluates conditions   │
│     ├── If approval node: record decision in workflow_approvals              │
│     ├── Update workflow_instance.current_node_id                             │
│     ├── AUTO-ADVANCE: If landed on conditional, immediately route through   │
│     ├── Add user to project_contributors                                     │
│     ├── Create workflow_history entry                                        │
│     ├── If rejected: auto-create project_issue                               │
│     ├── Always: create project_update for timeline visibility                │
│     └── assignProjectToNode() for next node (removes previous assignments)   │
│                                                                              │
│  3. COMPLETE WORKFLOW                                                        │
│     ├── Reached 'end' node OR status = 'completed'                          │
│     ├── Capture completed_snapshot (preserves final state)                   │
│     ├── Set completed_at timestamp                                           │
│     └── completeProject() - marks project as complete                        │
│                                                                              │
│  4. CANCEL WORKFLOW                                                          │
│     ├── Set status = 'cancelled'                                             │
│     └── Project remains but workflow is stopped                              │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

// Authorization flow in progressWorkflow()

// 1. SUPERADMIN BYPASS
const isSuperadmin = await isUserSuperadmin(supabase, currentUserId);
if (isSuperadmin) { /* Skip all other checks */ }

// 2. PROJECT ASSIGNMENT CHECK (for non-superadmins)
// User must be in project_assignments (not just created_by or assigned_user_id)
const isAssigned = await isUserAssignedToProject(supabase, currentUserId, projectId);
if (!isAssigned) {
  return { error: 'You must be assigned to this project to advance the workflow' };
}

// 3. NODE-SPECIFIC VALIDATION
const entityId = currentNode.entity_id;
const nodeType = currentNode.node_type;

if (nodeType === 'role' || nodeType === 'approval') {
  // For role/approval nodes, entity_id is a role_id
  const hasRequiredRole = await userHasRole(supabase, currentUserId, entityId);
  if (!hasRequiredRole) {
    return { error: 'Only users with the "[roleName]" role can advance this step' };
  }
}

if (nodeType === 'department') {
  // For department nodes, check if user has any role in this department
  const { data: userDeptRoles } = await supabase
    .from('user_roles')
    .select('roles!inner(department_id)')
    .eq('user_id', currentUserId)
    .eq('roles.department_id', entityId);

  if (!userDeptRoles?.length) {
    return { error: 'Only users in the "[deptName]" department can advance this step' };
  }
}

// workflow_connections.condition JSONB structure

// APPROVAL-BASED ROUTING (from approval nodes)
{
  "decision": "approved",        // or "rejected"
  "conditionValue": "approved"   // Alternative field (both checked)
}

// FORM-BASED ROUTING (from conditional nodes)
{
  "sourceFormFieldId": "budget",     // Field ID from form
  "conditionType": "greater_than",   // Evaluation operator
  "value": "10000",                  // Comparison value
  "value2": "50000"                  // For 'between' operator
}

// LABELED BRANCHES (for conditional node UI)
{
  "label": "High Budget",
  "color": "#22c55e",
  "conditionValue": "high"
}

// DEFAULT PATH (no condition - fallback route)
null  // or {}

-- workflow_history table structure
CREATE TABLE workflow_history (
  id              UUID PRIMARY KEY,
  workflow_instance_id UUID REFERENCES workflow_instances(id),
  from_node_id    UUID,                -- Previous node (null if start)
  to_node_id      UUID NOT NULL,       -- Node transitioned to
  handed_off_by   UUID,                -- User who triggered transition
  handed_off_to   UUID,                -- User assigned at new node
  handed_off_at   TIMESTAMPTZ DEFAULT NOW(),
  out_of_order    BOOLEAN DEFAULT FALSE,  -- Was this a skip?
  form_response_id UUID,               -- Link to form data if applicable
  notes           TEXT,                -- JSON for inline form data
  branch_id       TEXT DEFAULT 'main', -- For parallel tracking (legacy)
  approval_decision TEXT,              -- 'approved' or 'rejected'
  approval_feedback TEXT,              -- Feedback message
  project_update_id UUID,              -- Link to project_updates entry
  project_issue_id UUID                -- Link to project_issues (if rejected)
);

-- Indexes for efficient querying
CREATE INDEX idx_workflow_history_instance ON workflow_history(workflow_instance_id);
CREATE INDEX idx_workflow_history_handed_off_at ON workflow_history(handed_off_at DESC);

┌─────────────────────────────────────────────────────────────────────────────┐
│                         TIME TRACKING SYSTEM                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌────────────────────┐     ┌─────────────────────┐                         │
│  │   clock_sessions   │────▶│    time_entries     │                         │
│  │  (clock in/out)    │     │ (hours per task)    │                         │
│  └────────────────────┘     └─────────────────────┘                         │
│          │                            │                                      │
│          │                            ▼                                      │
│          │                  ┌─────────────────────┐                         │
│          │                  │  weekly_capacity    │                         │
│          │                  │     _summary        │                         │
│          │                  │      (view)         │                         │
│          │                  └─────────────────────┘                         │
│          │                                                                   │
│          ▼                                                                   │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │                        AUTO CLOCK-OUT SYSTEM                           │ │
│  │  - Runs before each time entry creation                                │ │
│  │  - Closes sessions older than 16 hours                                 │ │
│  │  - Sets is_auto_clock_out = true for tracking                         │ │
│  │  - Clock out time = clock in + 16 hours                               │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                              │
│  KEY RELATIONSHIPS:                                                          │
│  time_entries.task_id        → tasks.id                                     │
│  time_entries.project_id     → projects.id                                  │
│  time_entries.user_id        → user_profiles.id                             │
│  time_entries.clock_session_id → clock_sessions.id (optional)               │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

-- Auto clock-out function called before time entry creation
CREATE OR REPLACE FUNCTION auto_clock_out_stale_sessions()
RETURNS void AS $$
BEGIN
  -- Find all active sessions older than 16 hours and close them
  UPDATE clock_sessions
  SET
    clock_out_time = clock_in_time + INTERVAL '16 hours',
    is_active = false,
    is_auto_clock_out = true
  WHERE is_active = true
    AND clock_in_time < NOW() - INTERVAL '16 hours';
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

-- This function runs automatically via:
-- 1. Trigger on time_entries INSERT
-- 2. Scheduled cron job (if using pg_cron)
-- 3. Application code before creating entries

// TimeEntryService.getWeekStartDate()
getWeekStartDate(date: Date = new Date()): string {
  const d = new Date(date);
  const day = d.getDay();
  // Sunday = 0, Monday = 1, ... Saturday = 6
  // We want Monday as start of week (ISO standard)
  const diff = d.getDate() - day + (day === 0 ? -6 : 1);
  const monday = new Date(d.setDate(diff));
  return monday.toISOString().split('T')[0]; // YYYY-MM-DD
}

// Examples:
// Date: 2025-01-15 (Wednesday) → week_start_date: 2025-01-13 (Monday)
// Date: 2025-01-19 (Sunday)    → week_start_date: 2025-01-13 (Monday)
// Date: 2025-01-20 (Monday)    → week_start_date: 2025-01-20 (Monday)

interface WeeklySchedule {
  monday?: number;     // Hours available Monday (default: 8)
  tuesday?: number;    // Hours available Tuesday (default: 8)
  wednesday?: number;  // Hours available Wednesday (default: 8)
  thursday?: number;   // Hours available Thursday (default: 8)
  friday?: number;     // Hours available Friday (default: 8)
  saturday?: number;   // Hours available Saturday (default: 0)
  sunday?: number;     // Hours available Sunday (default: 0)
}

// Example: Part-time employee working Mon-Wed
{
  "monday": 8,
  "tuesday": 8,
  "wednesday": 8,
  "thursday": 0,
  "friday": 0,
  "saturday": 0,
  "sunday": 0
}
// available_hours would be 24 for this week

// User capacity metrics interface
interface UserCapacityMetrics {
  userId: string;
  userName: string;
  userEmail: string;
  weekStartDate: string;
  availableHours: number;    // From user_availability
  allocatedHours: number;    // From task_week_allocations
  actualHours: number;       // From time_entries
  utilizationRate: number;   // (actual / available) * 100
  remainingCapacity: number; // available - actual
}

// Department capacity aggregation
interface DepartmentCapacityMetrics {
  departmentId: string;
  departmentName: string;
  weekStartDate: string;
  teamSize: number;
  totalAvailableHours: number;
  totalAllocatedHours: number;
  totalActualHours: number;
  utilizationRate: number;
  remainingCapacity: number;
  userMetrics: UserCapacityMetrics[];
}

// Organization-wide metrics
interface OrgCapacityMetrics {
  weekStartDate: string;
  totalUsers: number;
  totalAvailableHours: number;
  totalAllocatedHours: number;
  totalActualHours: number;
  avgUtilizationRate: number;
  totalRemainingCapacity: number;
  departmentMetrics: DepartmentCapacityMetrics[];
}

// Three sources of allocation data:

// 1. Week-level allocations (most accurate)
const weekAllocatedHours = task_week_allocations
  .filter(a => a.assigned_user_id === userId && a.week_start_date === week)
  .reduce((sum, a) => sum + a.allocated_hours, 0);

// 2. Project-level allocations (from remaining task hours)
const projectAllocatedHours = projects
  .filter(p => user is assigned && p.status !== 'complete')
  .flatMap(p => p.tasks.filter(t => t.status !== 'done'))
  .reduce((sum, t) => sum + (t.remaining_hours ?? t.estimated_hours ?? 0), 0);

// 3. Task-level allocations (individual task assignments)
const taskAllocatedHours = tasks
  .filter(t => t.assigned_to === userId && t.status !== 'done')
  .reduce((sum, t) => sum + (t.remaining_hours ?? t.estimated_hours ?? 0), 0);

// Final allocation = max of all sources (avoids double-counting)
const allocatedHours = Math.max(
  weekAllocatedHours,
  projectAllocatedHours,
  taskAllocatedHours
);

// Get 8-week utilization trend for a user
const trend = await capacityService.getUserCapacityTrend(
  userId,
  8  // numberOfWeeks
);

// Returns array of weekly metrics:
// [
//   { weekStartDate: "2024-01-01", utilizationRate: 75, ... },
//   { weekStartDate: "2024-01-08", utilizationRate: 82, ... },
//   { weekStartDate: "2024-01-15", utilizationRate: 68, ... },
//   ...
// ]

// Use for charts and forecasting
const avgUtilization = trend.reduce((sum, w) => sum + w.utilizationRate, 0) / trend.length;
const isOverworked = trend.filter(w => w.utilizationRate > 95).length > 3;

// Standard form pattern in MovaLab
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { Form, FormField, FormItem, FormLabel, FormControl } from "@/components/ui/form";

const schema = z.object({
  name: z.string().min(1, "Name is required"),
  email: z.string().email("Invalid email"),
});

export function ExampleForm({ onSubmit }) {
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { name: "", email: "" },
  });

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <FormField
          control={form.control}
          name="name"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Name</FormLabel>
              <FormControl>
                <Input {...field} />
              </FormControl>
            </FormItem>
          )}
        />
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  );
}

// Standard service pattern in MovaLab
import { createClientSupabase } from '../supabase';

interface EntityWithDetails extends Entity {
  relatedData?: { id: string; name: string };
}

class ExampleService {
  /**
   * Get entity by ID with related data
   */
  async getById(id: string): Promise<EntityWithDetails | null> {
    const supabase = createClientSupabase();
    if (!supabase) return null;

    const { data, error } = await supabase
      .from('entities')
      .select(`
        *,
        related:related_table(id, name)
      `)
      .eq('id', id)
      .single();

    if (error) {
      console.error('Error fetching entity:', error);
      return null;
    }

    return data as EntityWithDetails;
  }

  /**
   * Create new entity
   */
  async create(data: EntityInsert): Promise<Entity | null> {
    const supabase = createClientSupabase();
    if (!supabase) return null;

    const { data: result, error } = await supabase
      .from('entities')
      .insert([data])
      .select()
      .single();

    if (error) {
      console.error('Error creating entity:', error);
      return null;
    }

    return result;
  }
}

// Export singleton
export const exampleService = new ExampleService();

npm run test:playwright        # Run Playwright E2E tests
npm run test:unit             # Run unit tests (permission system)
npm run test:integration      # Run integration tests
npm run test:permissions      # Run all permission tests + validation

LOCAL DEVELOPMENT:
[Your Machine]
├── Docker Desktop
│   └── Supabase Containers
│       ├── PostgreSQL (port 54322)
│       ├── Auth (GoTrue)
│       ├── PostgREST API (port 54321)
│       └── Studio UI (port 54323)
└── Next.js App (port 3000)
    └── Connects to localhost:54321

CLOUD PRODUCTION:
[Vercel / Your Host]
└── Next.js App
    └── Connects to xxx.supabase.co
        └── [Supabase Cloud]
            ├── Managed PostgreSQL
            ├── Auth
            └── API

# Run this to check all prerequisites are installed
echo "Node.js: $(node --version 2>/dev/null || echo 'NOT INSTALLED')"
echo "npm: $(npm --version 2>/dev/null || echo 'NOT INSTALLED')"
echo "Git: $(git --version 2>/dev/null || echo 'NOT INSTALLED')"
echo "Docker: $(docker --version 2>/dev/null || echo 'NOT INSTALLED')"
docker ps >/dev/null 2>&1 && echo "Docker: Running" || echo "Docker: NOT RUNNING"

# Step 1: Remove old Docker versions
sudo apt-get remove docker docker-engine docker.io containerd runc 2>/dev/null || true

# Step 2: Update package index
sudo apt-get update

# Step 3: Install prerequisites
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Step 4: Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Step 5: Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Step 6: Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Step 7: Add your user to docker group (avoids needing sudo)
sudo usermod -aG docker $USER
newgrp docker  # Or log out and back in

# Step 8: Start Docker service
sudo systemctl start docker
sudo systemctl enable docker  # Start on boot

# Step 9: Verify installation
docker --version
docker ps
docker run hello-world  # Should print "Hello from Docker!"

# Remove old versions
sudo dnf remove docker docker-client docker-client-latest docker-common

# Add repository
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

# Install Docker
sudo dnf install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start and enable
sudo systemctl start docker
sudo systemctl enable docker

# Add user to group
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker --version && docker ps

git clone https://github.com/itigges22/movalab.git
cd movalab

✓ Node.js v18+ detected
✓ Docker is running
✓ Migration file found
✓ Dependencies installed
✓ Starting Supabase...

Supabase started successfully!

API URL: http://127.0.0.1:54321
Studio URL: http://127.0.0.1:54323
DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres

Demo Users Created:
- superadmin@test.local / Test1234!
- exec@test.local / Test1234!
- manager@test.local / Test1234!
- pm@test.local / Test1234!
- designer@test.local / Test1234!
- dev@test.local / Test1234!

# Step 1: Install dependencies
npm install

# Step 2: Start Supabase
npx supabase start
# Wait for "Started supabase local development setup"

# Step 3: Verify status
npx supabase status
# Should show all services running with URLs

# Step 4: Seed database (optional)
npm run docker:seed

# Morning: Start development
npm run docker:start    # Wait 30-60 seconds
npm run dev             # Start Next.js

# Open: http://localhost:3000
# Login: exec@test.local / Test1234!

# Evening: Stop to save RAM
npm run docker:stop

# Local Supabase (defaults from npx supabase start)
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0

# Optional: Enable demo mode for testing
NEXT_PUBLIC_DEMO_MODE=true

supabase/migrations/20250129000000_baseline.sql

# Step 1: Create migration file
npx supabase migration new add_feature_name
# Creates: supabase/migrations/YYYYMMDDHHMMSS_add_feature_name.sql

# Step 2: Write your SQL (see example below)

# Step 3: Test locally
npm run docker:reset    # Resets and applies all migrations
npm run docker:health   # Verify everything works

# Step 4: Push to cloud
npm run cloud:migrate
npm run cloud:status    # Verify it applied

-- Create new table
CREATE TABLE IF NOT EXISTS feature_flags (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    name TEXT NOT NULL UNIQUE,
    enabled BOOLEAN DEFAULT false,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- ALWAYS enable RLS
ALTER TABLE feature_flags ENABLE ROW LEVEL SECURITY;

-- Add policies
CREATE POLICY "Superadmins can manage feature flags"
ON feature_flags FOR ALL
USING (
    EXISTS (
        SELECT 1 FROM user_profiles
        WHERE id = auth.uid()
        AND is_superadmin = true
    )
);

# Check Docker
docker --version && docker ps

# Check Supabase
npx supabase status

# Check Node
node --version && npm --version

# Check migrations
ls supabase/migrations/
npm run cloud:status

# Full reset (nuclear option)
npm run docker:clean
rm -rf node_modules
npm install
npm run docker:start

# One command starts everything
npm run dev:demo

# This will:
# 1. Check Docker is installed and running
# 2. Start Supabase containers (PostgreSQL, Auth, API, etc.)
# 3. Wait for services to be ready
# 4. Start Next.js with demo mode enabled

# When done, stop Docker to free RAM (2-4 GB typical usage)
npm run docker:stop

# If Supabase containers are already running:
# 1. Add to .env.local:
NEXT_PUBLIC_DEMO_MODE=true

# 2. Start the dev server:
npm run dev

# 1. Create a Cloud Supabase project at supabase.com
#    Name it "movalab-prod" (separate from any demo project)

# 2. Link and push migrations
npx supabase link --project-ref YOUR_PROJECT_REF
npx supabase db push

# 3. Create real users via Supabase dashboard or app invites
#    Do NOT use demo seed users in production!

# 4. Update .env.local for cloud
NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your-cloud-key
# NEXT_PUBLIC_DEMO_MODE=true  # <-- Remove or set to false

# 5. Stop Docker (no longer needed)
npm run docker:stop

# 6. Start in production mode
npm run dev

# Set these environment variables in Vercel dashboard:
NEXT_PUBLIC_SUPABASE_URL=https://your-demo-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your-publishable-key
NEXT_PUBLIC_DEMO_MODE=true
NEXT_PUBLIC_APP_URL=https://demo.your-domain.com

# 1. Generate a CRON_SECRET
openssl rand -hex 32

# 2. Get your Supabase service_role key from:
#    Supabase Dashboard → Settings → API → service_role (secret)

# 3. Add to Vercel Environment Variables:
NEXT_PUBLIC_DEMO_MODE=true
DEMO_MODE=true
CRON_SECRET=<your-generated-secret>
DEMO_SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>

# 4. Verify in Vercel Dashboard → Settings → Crons
#    You should see: /api/cron/reset-demo-data at 0 0 * * *

curl -X GET 'https://demo.your-domain.com/api/cron/reset-demo-data' \
  -H 'Authorization: Bearer YOUR_CRON_SECRET'

# Success: {"success":true,"message":"Demo data reset successfully",...}
# Not demo mode: {"error":"Demo mode is not enabled",...} (403)
# Bad secret: {"error":"Unauthorized"} (401)

// Client-side detection
import { isDemoMode } from '@/lib/demo-mode';

if (isDemoMode()) {
  // Show demo UI
}

// Blocking actions (client)
import { isActionBlocked, getBlockedActionMessage } from '@/lib/demo-mode';

if (isActionBlocked('delete_project')) {
  toast.error(getBlockedActionMessage('delete_project'));
  return;
}

// Blocking actions (API)
import { checkDemoModeForDestructiveAction } from '@/lib/api-demo-guard';

export async function DELETE(request: NextRequest) {
  const blocked = checkDemoModeForDestructiveAction('delete_project');
  if (blocked) return blocked;
  // Continue with delete...
}

// Adding new blocked actions:
// 1. Add type to lib/demo-mode.ts BlockedAction
// 2. Add message to BLOCKED_MESSAGES
// 3. Use in your component or API route

# Full database reset (destroys ALL local data)
npm run docker:seed

# Reset Docker completely if corrupted
npm run docker:clean  # stops + prunes containers
npm run dev:demo      # start fresh

# Demo mode not working? Check:
# 1. NEXT_PUBLIC_DEMO_MODE=true in .env.local
# 2. Restart dev server (env read at startup)
# 3. Clear browser cache (Ctrl+Shift+R)

# High memory usage?
npm run docker:stop   # Stop when not in use
# Or use cloud demo mode instead

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/movalab.git

# 2. Create branch
git checkout -b feature/your-feature-name

# 3. Make changes and test
npm run build
npm run test

# 4. Push and create PR
git push origin feature/your-feature-name

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Navigate to project
cd movalab

# Start Claude Code
claude

# Claude reads CLAUDE.md automatically and understands:
# - Project structure (90k+ lines)
# - Database schema (33 tables, 100+ RLS policies)
# - Permission system (~40 permissions)
# - API patterns (83+ endpoints)
# - Coding conventions

# Interactive permission debugger
npm run debug:permissions
# Prompts for user ID and permission name
# Shows: user roles, inherited permissions, context checks, final result

# Validate all permissions in the system
npm run validate:permissions
# Checks: orphaned permissions, circular dependencies, missing defaults

# Fix common permission problems
npm run fix:permissions
# Repairs: missing role assignments, default role setup, permission cache

# Test RLS policies directly in psql
docker exec -it supabase_db_movalab psql -U postgres -d postgres

# Check permission for specific user
SELECT check_user_permission('user-uuid', 'MANAGE_PROJECTS');

# List all effective permissions for a user
SELECT p.name, p.description
FROM permissions p
JOIN role_permissions rp ON p.id = rp.permission_id
JOIN user_roles ur ON rp.role_id = ur.role_id
WHERE ur.user_id = 'user-uuid';

# Development Commands
npm run dev            # Start development server
npm run dev:fresh      # Kill port 3000 and restart
npm run build          # Production build (catches type errors)
npm run lint           # Run ESLint
npx tsc --noEmit       # Type check without build

# Docker Commands
npm run docker:start   # Start Supabase locally
npm run docker:stop    # Stop Supabase
npm run docker:reset   # Reset database completely
npm run docker:logs    # View Docker logs

# Database Commands
npx supabase db push   # Apply migrations
npx supabase db reset  # Reset and reseed
npx supabase gen types typescript  # Regenerate types

# Debug Commands
npm run debug:permissions  # Interactive permission debugger
npm run validate:permissions  # Check permission consistency
npm run test:rls       # Test RLS policies

# Useful psql Commands (inside Docker)
docker exec -it supabase_db_movalab psql -U postgres -d postgres
\dt                    # List tables
\d table_name          # Describe table
\df function_name      # Describe function
SELECT * FROM pg_stat_activity;  # Active queries