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/*