Client_Fe/PROJECT_REFERENCE.md

# HexaFitness Client Project Reference

## Overview

- App name: `hexa-fitness-client`
- Stack: Next.js 16 App Router, React 19, TypeScript, Tailwind CSS 4
- UI patterns: custom app components plus reusable `src/components/ui/*`
- Notifications: `sonner`
- Charts: `recharts`
- Theme handling: `next-themes`
- Main app area: dashboard for gym management
- Public flows: landing page, request access, sandbox demo, activation, login

## Environment

- Core API base URL: `NEXT_PUBLIC_CORE_API_URL`
- Default fallback in code: `http://localhost:5111`

## Scripts

- `npm run dev` - start development server
- `npm run build` - production build
- `npm run start` - run production server
- `npm run lint` - run ESLint

## App Structure

### Root App Files

- `src/app/layout.tsx` - global layout, fonts, theme provider, tooltip provider, toast provider
- `src/app/globals.css` - global styling
- `src/app/page.tsx` - redirects `/` to `/landing-page`

### Screens / Routes

| Route | File | Purpose |
| --- | --- | --- |
| `/` | `src/app/page.tsx` | Root redirect to landing page |
| `/landing-page` | `src/app/landing-page/page.tsx` | Marketing website |
| `/login` | `src/app/login/page.tsx` | User login form |
| `/request-access` | `src/app/request-access/page.tsx` | Mobile OTP onboarding request flow |
| `/sandbox/[token]` | `src/app/sandbox/[token]/page.tsx` | Demo dashboard / sandbox experience |
| `/activation/[token]` | `src/app/activation/[token]/page.tsx` | Multi-step gym activation flow |
| `/dashboard` | `src/app/dashboard/page.tsx` | Dashboard overview |
| `/dashboard/attendance` | `src/app/dashboard/attendance/page.tsx` | Attendance tracking |
| `/dashboard/members` | `src/app/dashboard/members/page.tsx` | Member listing, details, actions |
| `/dashboard/memberships` | `src/app/dashboard/memberships/page.tsx` | Gym plans / memberships |
| `/dashboard/payments` | `src/app/dashboard/payments/page.tsx` | Payments and invoices |
| `/dashboard/workout-plans` | `src/app/dashboard/workout-plans/page.tsx` | Workout plan management |
| `/dashboard/meal-plans` | `src/app/dashboard/meal-plans/page.tsx` | Meal plan management |
| `/dashboard/staff` | `src/app/dashboard/staff/page.tsx` | Staff management |
| `/dashboard/feed` | `src/app/dashboard/feed/page.tsx` | Feed management |
| `/dashboard/tickets` | `src/app/dashboard/tickets/page.tsx` | Support tickets |
| `/dashboard/payouts` | `src/app/dashboard/payouts/page.tsx` | Wallet, KYC, payout setup |
| `/dashboard/reports` | `src/app/dashboard/reports/page.tsx` | Revenue, attendance, trends |

### Layout and Loading Files

- `src/app/dashboard/layout.tsx` - auth gate, wraps dashboard in `DashboardShell`
- `src/app/dashboard/loading.tsx` - dashboard loading state
- `src/app/dashboard/attendance/loading.tsx`
- `src/app/dashboard/feed/loading.tsx`
- `src/app/dashboard/members/loading.tsx`
- `src/app/dashboard/memberships/loading.tsx`
- `src/app/dashboard/meal-plans/loading.tsx`
- `src/app/dashboard/payments/loading.tsx`
- `src/app/dashboard/payouts/loading.tsx`
- `src/app/dashboard/reports/loading.tsx`
- `src/app/dashboard/staff/loading.tsx`
- `src/app/dashboard/tickets/loading.tsx`
- `src/app/dashboard/workout-plans/loading.tsx`

## Navigation

- Source: `src/lib/nav.ts`
- Main dashboard nav items:
  - Dashboard
  - Attendance
  - Members
  - Memberships
  - Payments & Invoices
  - Workout Plans
  - Meal Plans
  - Staff
  - Feed
  - Tickets
  - Payouts & Wallet
  - Reports
- Mobile primary keys: `dashboard`, `members`, `attendance`, `payments`

## API Layer

### Core HTTP

- `src/lib/api/core-http.ts`
- Responsibilities:
  - centralized `apiRequest`
  - auth-aware fetch with cookies
  - auto refresh on `401`
  - redirect to `/login` when session refresh fails
  - `ApiError` handling
  - shared helpers: `findField`, `refreshSession`

### Auth APIs

- `src/lib/api/auth.ts`
  - `login(request)` - login user and extract access/refresh token fields
- `src/lib/api/session.ts`
  - `logout()` - clear server cookies and local auth flag
  - `refreshSession()` - re-exported refresh helper

### Onboarding / Activation APIs

- `src/lib/api/onboarding.ts`
  - `checkMobileNumber(request)` - check if onboarding already exists
  - `sendMobileOtp(request)` - send request-access OTP
  - `verifyMobileOtp(request)` - verify request-access OTP
  - `createOnboardingRequest(requestAccessToken, request)` - submit gym onboarding request
  - `getSandboxStatus(sandboxToken)` - fetch demo/sandbox status
  - `updateSandboxProgress(sandboxToken, update)` - track sandbox usage/tour progress
- `src/lib/api/activation.ts`
  - `sendActivationEmailOtp(token, request)` - send activation email OTP
  - `verifyActivationEmailOtp(token, request)` - verify activation email OTP
  - `uploadNic(token, nicNumber, frontImage, backImage)` - upload identity documents
  - `updateGymProfile(token, request)` - save gym profile info
  - `setPaymentMethod(token, request)` - save activation payment method
  - `chargeAndActivate(token)` - finalize activation
  - `getActivationChecklist(token)` - fetch post-activation checklist

### Dashboard Business APIs

- `src/lib/api/profile.ts`
  - `getMyProfile()` - fetch logged-in client profile
- `src/lib/api/stats.ts`
  - `getStatSummary()` - dashboard summary stats
  - `getMonthlyRevenue()` - revenue chart data
  - `getRecentPayments()` - recent payment list
  - `getRecentAttendance()` - recent attendance list
- `src/lib/api/attendance.ts`
  - `getAllAttendance()` - full attendance records
  - `getTodayAttendance()` - today check-ins
  - `getAttendanceCounts(fromDate, toDate)` - aggregated attendance counts
- `src/lib/api/customers.ts`
  - `getMembers()` - list members with subscriptions
  - `getMember(customerId)` - member detail
  - `createMember(input)` - add member
  - `updateMember(customerId, input)` - edit member
  - `deleteMember(customerId)` - remove member
- `src/lib/api/gym-plans.ts`
  - `getGymPlans(includeInactive)` - list gym membership plans
  - `getGymPlan(id)` - single gym plan
  - `createGymPlan(input)` - create gym plan
  - `updateGymPlan(id, input)` - update gym plan
  - `deleteGymPlan(id, hard)` - delete or soft delete plan
- `src/lib/api/subscriptions.ts`
  - `getSubscription(id)` - subscription summary
  - `getSubscriptionPayments(id)` - subscription payment history
  - `recordSubscriptionPayment(id, input)` - add payment to subscription
  - `addSubscriptionMember(id, customerId)` - attach member to subscription
  - `removeSubscriptionMember(id, subscriptionMemberId)` - remove member from subscription
- `src/lib/api/invoices.ts`
  - `getMemberInvoices()` - list invoices
  - `getMemberInvoice(id)` - invoice detail
- `src/lib/api/payments-enablement.ts`
  - `getPaymentTracks()` - available payout/payment tracks
  - `selectPaymentTrack(request)` - choose a payment track
  - `submitPayoutKyc(brCertificate, bankProof)` - upload payout KYC docs
  - `getKycStatus()` - read KYC state
  - `getWallet()` - wallet summary
  - `getPayoutSchedule()` - payout schedule data
- `src/lib/api/staff.ts`
  - `getStaff()` - list staff
  - `getStaffMember(staffId)` - single staff member
  - `createStaff(input)` - create staff member
  - `updateStaff(staffId, input)` - update staff
  - `deleteStaff(staffId, softDelete)` - delete staff member
- `src/lib/api/feed.ts`
  - `getFeed()` - list feed posts
  - `createFeedPost(input)` - create post
  - `deleteFeedPost(postId)` - delete post
  - `likePost(postId)` - like post
  - `unlikePost(postId)` - unlike post
  - `isPostLiked(postId)` - fetch current user like state
- `src/lib/api/tickets.ts`
  - `getTickets()` - list support tickets
  - `getTicket(id)` - ticket detail
  - `getTicketCategories()` - support categories
  - `createTicket(mainReason, ticketCategoryId)` - open ticket
  - `sendTicketMessage(id, message)` - add ticket message
  - `submitTicketFeedback(id, rating, feedback)` - submit support feedback
  - `closeTicket(id)` - close ticket
  - `deleteTicket(id)` - delete ticket

### Plan APIs

- `src/lib/api/workout-plans.ts`
  - `getWorkoutPlans()`
  - `getWorkoutCategories()`
  - `createWorkoutCategory(name, description)`
  - `createWorkoutPlan(input)`
  - `updateWorkoutPlan(id, input)`
  - `deleteWorkoutPlan(id)`
  - `assignWorkoutPlan(id, customerId, notes)`
  - `getWorkoutItems(planId)`
  - `createWorkoutItem(planId, title, detail)`
- `src/lib/api/meal-plans.ts`
  - `getMealPlans()`
  - `getMealCategories()`
  - `createMealCategory(name, description)`
  - `createMealPlan(input)`
  - `updateMealPlan(id, input)`
  - `deleteMealPlan(id)`
  - `assignMealPlan(id, customerId, notes)`
  - `getMealItems(planId)`
  - `createMealItem(planId, title, detail)`

## Components

### Shared App Components

- `src/components/theme-provider.tsx` - global theme wrapper

### Marketing Components

- `src/components/marketing/marketing-header.tsx`
- `src/components/marketing/hero-section.tsx`
- `src/components/marketing/features-section.tsx`
- `src/components/marketing/cta-section.tsx`
- `src/components/marketing/marketing-footer.tsx`

### Onboarding Components

- `src/components/onboarding/onboarding-layout.tsx` - shared layout for request access and activation flows

### Dashboard / Hexa Components

- `src/components/hexa/app-sidebar.tsx`
- `src/components/hexa/attendance-chart-card.tsx`
- `src/components/hexa/back-button.tsx`
- `src/components/hexa/checkin-list.tsx`
- `src/components/hexa/client-profile-context.tsx`
- `src/components/hexa/dashboard-shell.tsx`
- `src/components/hexa/data-table.tsx`
- `src/components/hexa/detail-panel.tsx`
- `src/components/hexa/filter-bar.tsx`
- `src/components/hexa/info-banner.tsx`
- `src/components/hexa/mobile-nav.tsx`
- `src/components/hexa/page-header.tsx`
- `src/components/hexa/page-skeleton.tsx`
- `src/components/hexa/pagination-bar.tsx`
- `src/components/hexa/post-card.tsx`
- `src/components/hexa/refresh-button.tsx`
- `src/components/hexa/revenue-chart-card.tsx`
- `src/components/hexa/sandbox-tour.tsx`
- `src/components/hexa/selectable-card.tsx`
- `src/components/hexa/site-header.tsx`
- `src/components/hexa/stat-card.tsx`
- `src/components/hexa/status-badge.tsx`
- `src/components/hexa/theme-toggle.tsx`

### Dashboard View Components

- `src/components/hexa/views/feed-view.tsx`
- `src/components/hexa/views/gym-plans-view.tsx`
- `src/components/hexa/views/payments-enablement-view.tsx`
- `src/components/hexa/views/placeholder-view.tsx`
- `src/components/hexa/views/plan-detail-panel.tsx`
- `src/components/hexa/views/plan-editor-dialog.tsx`
- `src/components/hexa/views/plan-management-view.tsx`
- `src/components/hexa/views/staff-view.tsx`
- `src/components/hexa/views/member-subscription-card.tsx`

### Dialog / Action Components

- `src/components/hexa/views/add-category-dialog.tsx`
- `src/components/hexa/views/add-group-members-dialog.tsx`
- `src/components/hexa/views/add-gym-plan-dialog.tsx`
- `src/components/hexa/views/create-feed-dialog.tsx`
- `src/components/hexa/views/member-form-dialog.tsx`
- `src/components/hexa/views/record-payment-dialog.tsx`
- `src/components/hexa/views/staff-form-dialog.tsx`

### Reusable UI Components

- `src/components/ui/alert-dialog.tsx`
- `src/components/ui/alert.tsx`
- `src/components/ui/avatar.tsx`
- `src/components/ui/badge.tsx`
- `src/components/ui/breadcrumb.tsx`
- `src/components/ui/button.tsx`
- `src/components/ui/calendar.tsx`
- `src/components/ui/card.tsx`
- `src/components/ui/chart.tsx`
- `src/components/ui/checkbox.tsx`
- `src/components/ui/combobox.tsx`
- `src/components/ui/command.tsx`
- `src/components/ui/dialog.tsx`
- `src/components/ui/dropdown-menu.tsx`
- `src/components/ui/empty.tsx`
- `src/components/ui/field.tsx`
- `src/components/ui/input-group.tsx`
- `src/components/ui/input-otp.tsx`
- `src/components/ui/input.tsx`
- `src/components/ui/label.tsx`
- `src/components/ui/pagination.tsx`
- `src/components/ui/popover.tsx`
- `src/components/ui/progress.tsx`
- `src/components/ui/radio-group.tsx`
- `src/components/ui/scroll-area.tsx`
- `src/components/ui/select.tsx`
- `src/components/ui/separator.tsx`
- `src/components/ui/sheet.tsx`
- `src/components/ui/sidebar.tsx`
- `src/components/ui/skeleton.tsx`
- `src/components/ui/sonner.tsx`
- `src/components/ui/spinner.tsx`
- `src/components/ui/switch.tsx`
- `src/components/ui/table.tsx`
- `src/components/ui/tabs.tsx`
- `src/components/ui/textarea.tsx`
- `src/components/ui/tooltip.tsx`

## Hooks and Client Utilities

### Hooks

- `src/hooks/use-mobile.ts` - mobile breakpoint helper
- `src/lib/use-media-query.ts` - media query hook
- `src/lib/use-fetch.ts` - lightweight async data fetching helper

### Utility / Support Files

- `src/lib/auth/token-service.ts` - local auth/session flag helpers
- `src/lib/format.ts` - formatting helpers for currency, dates, etc.
- `src/lib/nav.ts` - dashboard navigation config
- `src/lib/utils.ts` - shared utility helpers
- `src/lib/validation.ts` - validation and masking helpers for onboarding/activation

## Models / Types

- `src/lib/models/api.ts` - base API response types
- `src/lib/models/auth.ts` - auth request/result types
- `src/lib/models/activation.ts` - activation flow types
- `src/lib/models/attendance.ts` - attendance-related types
- `src/lib/models/customer.ts` - member and customer types
- `src/lib/models/feed.ts` - feed post types
- `src/lib/models/gym-plan.ts` - gym membership plan types
- `src/lib/models/invoice.ts` - invoice types
- `src/lib/models/onboarding.ts` - request-access and sandbox types
- `src/lib/models/payments-enablement.ts` - wallet, KYC, payout types
- `src/lib/models/plan.ts` - reusable workout/meal plan types
- `src/lib/models/profile.ts` - client profile types
- `src/lib/models/staff.ts` - staff types
- `src/lib/models/stats.ts` - dashboard stat types
- `src/lib/models/subscription.ts` - subscription and payment types
- `src/lib/models/ticket.ts` - support ticket types

## Public Assets

### Images

- `public/images/auth-bg.png`
- `public/images/gym-bg.png`
- `public/images/landing-hero.png`
- `public/images/logo.png`
- `public/images/hexa_Logo.png`
- `public/images/Hexa_Fitness.png`
- `public/images/hexa-Logo-white.png`
- `public/images/hexa-Logo-black.png`
- `public/images/mobile-bg.png`

### Other Public Files

- `public/file.svg`
- `public/globe.svg`
- `public/next.svg`
- `public/vercel.svg`
- `public/window.svg`

## Current Functional Areas

- Marketing website
- Authentication
- Request access onboarding
- Sandbox demo experience
- Gym activation workflow
- Dashboard overview analytics
- Attendance management
- Member management
- Membership / gym plan management
- Payments and invoices
- Workout plan management
- Meal plan management
- Staff management
- Feed / posts
- Ticketing / support
- Payout and wallet setup
- Reports

## Suggested Use Of This File

- Use this document as the first-stop project map for onboarding
- Update it when new routes, API modules, or components are added
- Keep API method names in sync with `src/lib/api/*`