Gym CRM
A gym management app with QR attendance, subscription checks, staff roles and inventory checkout.
Built as a working showcase that can serve as a foundation for a customized business implementation.
Inspect the evidence
Review the implementation, data model and tests in the repository.
What I built
- Front-desk check-in terminal verifying digital QR passes with a 2-minute duplicate scan window
- Member directory managing personal profiles, emergency contacts, and ACTIVE, EXPIRED, FROZEN subscription states
- Server-side RBAC across 5 roles (ADMIN, MANAGER, TRAINER, RECEPTIONIST, MEMBER) with registration anti-escalation
- 13-model PostgreSQL schema via Prisma ORM modeling members, plans, attendance, workouts, and POS orders
- Workout programming and macronutrient dietary targets with Gemini 1.5 Flash and deterministic template fallbacks
- Point-of-sale merchandise catalog tracking inventory stock, unit pricing, order records, and itemized receipts
- Class scheduling matrix with trainer allocations and room capacity threshold limits
- Dual-mode data persistence connecting to PostgreSQL with an in-memory fallback for reliable evaluations
- High-contrast responsive interface optimized for front-desk terminal lighting and mobile member viewing
Front-Desk Bottlenecks, Expired Entries & Role Ambiguity
Fitness facilities struggle during rush hours with slow manual member lookups, members slipping past reception with lapsed or expired subscriptions, and attendance recorded on fragmented paper rosters. Furthermore, operational staff (receptionists, trainers, managers) require different permission tiers than gym members, yet basic gym tools often expose sensitive administrative data without server-side authorization boundaries.
Operational Access Verification & Scoped Workflows
Gym CRM implements a front-desk check-in workflow backed by digital QR pass verification that checks membership status and expiration dates before logging attendance, guarded by a 2-minute collision window against duplicate scans. Server-side RBAC isolates 5 roles (Admin, Manager, Trainer, Receptionist, Member), while 13 relational models tie member profiles, attendance logs, POS inventory, and audit logs together.
03 / PRODUCT EXPERIENCE
Core Capabilities & Workflow
Front-Desk Operations & Facility Attendance
An operational dashboard displaying daily front-desk check-in counts, active subscription rosters, peak-hour occupancy distribution, and facility membership totals.
Allows receptionists to monitor current gym floor occupancy during peak traffic windows while providing management with verified attendance records.
Operations dashboard with daily check-in logs, active member totals, and recurring revenue metrics
Member Directory & Subscription Lifecycle States
A structured member registry tracking personal profiles, emergency contacts, digital QR pass identifiers, and subscription states (ACTIVE, EXPIRED, FROZEN) with expiration dates.
Prevents unauthorized facility entry by clearly flagging expired and frozen subscriptions before members reach the workout floor.
Member CRM directory with quick search, subscription status badges, and digital QR codes
5-Role RBAC & Partitioned Registration
Server-side role enforcement across 5 roles (ADMIN, MANAGER, TRAINER, RECEPTIONIST, MEMBER), paired with a registration flow that restricts public signups to MEMBER or ADMIN to prevent privilege escalation.
Restricts sensitive administrative routes, audit logs, and financial ledgers to authorized staff while providing gym members a focused personal portal.
Dual registration onboarding allowing users to select Administrator or Gym Member accounts with server-side RBAC
Class Capacity & Trainer Scheduling Matrix
A group fitness scheduling matrix displaying class times, room capacities, assigned trainers, and registered participant counts.
Structures group class capacities to prevent overcrowding and allows trainers to review attendee rosters in advance.
Workout Programming & Dietary Macros with Deterministic Fallbacks
Exercise routine construction (sets, repetitions, target muscle groups) and daily macro targets (calories, protein, carbohydrates, fats) backed by Google Gemini 1.5 Flash and deterministic rule-based template fallbacks.
Provides structured fitness and nutrition plans to trainers and members even when external AI API keys are unconfigured or external networks time out.
Front-Desk POS Inventory & Itemized Receipts
A point-of-sale catalog for on-site merchandise (supplements, beverages, training gear) tracking stock quantities, unit prices, itemized orders, and receipt generation alongside membership plan billing.
Maintains an internal sales record for front-desk retail counter transactions without requiring an external hardware POS integration.
Financial transaction ledger with payment method records, invoice snapshots, and printable receipts
04 / TECHNICAL ARCHITECTURE
Engineering Foundation & Architecture
Front-Desk Attendance Verification & Duplicate Scan Guard
During morning and evening peaks, front-desk staff must process member check-ins rapidly while preventing lapsed entries. The check-in endpoint queries the member record by indexed QR code, validates that user status is ACTIVE, and verifies that the most recent membership plan has an ACTIVE status with an endDate in the future. To prevent double-scanning caused by scanner latency or multiple touches, the handler checks whether an attendance record already exists within a 2-minute collision window, immediately returning HTTP 409 Conflict if detected, before logging the verified entry and an immutable audit trail.
5-Role Server-Side RBAC & Anti-Escalation Safeguards
A gym management system serves staff with administrative obligations and gym members with self-service needs. Authorization is modeled across 5 distinct roles: ADMIN, MANAGER, TRAINER, RECEPTIONIST, and MEMBER. Rather than relying on UI component hiding, API routes enforce server-side validation using requireRole(). The public registration endpoint explicitly partitions input, permitting only MEMBER or ADMIN (for demo evaluation) and rejecting arbitrary role escalation to MANAGER, TRAINER, or RECEPTIONIST. Privileged endpoints like /api/audit-logs strictly reject MEMBER tokens with HTTP 403 Forbidden, proven via automated verification scripts.
13-Model Relational Schema & Subscription Lifecycle Integrity
Facility operations inherently link personal identities, access permissions, financial transactions, and physical presence. Using Prisma ORM with PostgreSQL, the system models 13 relational entities: User, MemberProfile, MembershipPlan, MemberMembership, Attendance, Exercise, WorkoutPlan, NutritionPlan, Payment, Product, OrderItem, Notification, and AuditLog. Foreign-key constraints guarantee that attendance scans and POS order items link directly to valid member and inventory records, preventing orphaned logs while modeling subscription state transitions (ACTIVE, EXPIRED, FROZEN).
AI-Assisted Generation with Deterministic Template Fallbacks
The workout and nutrition modules integrate Google Gemini 1.5 Flash to generate personalized training splits and macronutrient distributions based on member fitness goals and physical attributes. To prevent operational disruptions from external API quota exhaustion, network timeouts, or missing environment variables, all generation calls pass through Zod schema validation and fall back to deterministic, rule-based template logic. This guarantees that members and trainers receive structured, error-free workout regimens and macronutrient targets under all network conditions.
05 / VERIFIED IMPLEMENTATION
Engineering Evidence & Facility Workflows
Front-desk access validation, server-side RBAC, and transactional operations verified directly in the codebase.
Pre-Persistence Access Validation
Access is strictly validated before attendance is persisted. Every front-desk scan validates user status, verifies active subscription dates, and enforces a 120-second duplicate collision window (preventing scanner double-reads with an immediate HTTP 409 Conflict).
5-Role Server-Side Authorization Boundary
| Role | Scope | Check-in | POS Retail | Member Data | Workouts | Audit Logs |
|---|---|---|---|---|---|---|
| ADMIN | Full system administration | ✓ | ✓ | ✓ | ✓ | ✓ |
| MANAGER | Operational management | ✓ | ✓ | ✓ | ✓ | ✓ |
| TRAINER | Training floor & routines | ✓ | — | ✓ | ✓ | — |
| RECEPTIONIST | Front-desk intake & POS | ✓ | ✓ | ✓ | — | — |
| MEMBER | Self-service member portal | — | — | Own | Own | — |
Anti-privilege escalation at registration: Public registration endpoints strictly restrict new accounts to MEMBER (or demo ADMIN). Operational staff roles (MANAGER, TRAINER, RECEPTIONIST) cannot be self-provisioned by external callers.
Access validation before persistence
Every front-desk scan validates active membership status and blocks rapid duplicate scans via a 120-second temporal guard.
Atomic POS counter retail checkout
Pro shop counter sales validate stock, decrement inventory, and record payments atomically via ACID transactions.
Server-Side Security Guarantees
Signed Session Cookies
Session cookies are HMAC-SHA256 signed and verified in constant time via crypto.timingSafeEqual, neutralizing timing side-channel attacks.
Registration Role Partition
Public registration partitions input roles to MEMBER or demo ADMIN, strictly prohibiting unauthorized self-assignment of staff permissions.
Sensitive Data Redaction
Sensitive keys (password, token, secret, cookie) are automatically redacted prior to AuditLog insertion. Inspection is strictly restricted to ADMIN and MANAGER.
Floor operations remain functional without external API availability.
Workout and macronutrient planning uses Gemini 1.5 Flash with input truncation (500 chars) and strict Zod schema validation over generated JSON structures.
Rule-based programmatic generation on network or quota exhaustion.
If the API key is missing, network times out, or parsing fails, execution falls back immediately to deterministic local formulas. Floor operations never encounter downtime.
Runtime Contracts & Integrity Across 13 Relational Models
Gym CRM's operational dependability is anchored in PostgreSQL relational constraints, strict TypeScript contracts, Zod ingress validation at route boundaries, and atomic database transactions across front-desk enrollment and POS counter sales.
05 / ENGINEERING DECISIONS
Technical decisions & trade-offs
Two-Minute Anti-Collision Window on Reception Scans
Enforce a 2-minute collision threshold on the /api/attendance/check-in endpoint that rejects repeat check-in requests for the same member with HTTP 409 Conflict.
During busy hours, optical scanners frequently trigger multi-read pulses or front-desk staff accidentally scan a pass twice. Rejecting rapid repeat scans prevents corrupted attendance metrics while ensuring valid entries pass through cleanly.
Partitioned Role Onboarding & Endpoint-Level RBAC
Strictly validate role input in the public registration handler to allow only MEMBER or ADMIN (for demo access), while executing requireRole() checks on all administrative endpoints.
Allowing arbitrary role assignment at registration would allow malicious clients to claim MANAGER or RECEPTIONIST privileges. Server-side checks ensure that MEMBER sessions are structurally barred from accessing member rosters, audit logs, or facility settings.
Normalized Relational Data Modeling via Prisma ORM
Model gym operations across 13 relational entities with explicit foreign-key constraints linking users, membership plans, check-ins, workout programs, and POS transactions.
Gym operations are deeply relational: an attendance entry must reference a member with an active subscription, and a POS order item must link to an existing product. Relational constraints prevent orphaned logs and maintain financial and attendance auditability.
Dual-Mode PostgreSQL Storage with In-Memory Fallback
Implement a database abstraction that connects to PostgreSQL via Prisma in production, while maintaining an in-memory repository fallback for standalone demo sessions.
Public portfolio visitors evaluate applications under varying network and database availability conditions. The dual-mode architecture guarantees that front-desk check-in, member browsing, and workout workflows remain fully explorable without database cold-start failures.
06 / REFLECTIONS & LEARNINGS
What This Project Demonstrated
Enforcing Authorization Boundaries at the Route Layer
Designing Gym CRM demonstrated that securing facility software requires isolating API routes rather than relying on conditional component rendering. Verifying role claims on each request and returning HTTP 403 Forbidden to unauthorized tokens prevents IDOR vulnerabilities and unauthorized access to member databases.
Guarding AI-Assisted Features with Rule-Based Fallbacks
Relying on external LLMs for operational routines introduces latency, quota exhaustion risks, and network dependencies. Pairing Google Gemini generation with Zod schema validation and deterministic template fallbacks ensures the application delivers consistent workout and nutritional protocols regardless of API status.
Deployed interactive web application on Vercel
Read the implementation and browse its history.
Inspect the layouts in the screenshots and demo.
Explore the architecture and decisions in this case study.
Explore the Application Live
Access the dashboard, operational modules, and interactive workflows in a safe, read-only demo environment.
🔒 Read-only environment · Synthetic data
OPERATIONS & DATA ANALYTICS
Interested in operational workflow tools or tracking dashboards?
I welcome technical discussions on structuring attendance workflows, relational data modeling, or software learning and collaboration.
Looking to adapt a similar system for your facility? Explore the custom gym management software service →