Building FitKalp CRM — A Gym Management System, End to End

Why I Built This

Managing a gym is surprisingly messy. Members join every week, subscriptions expire without anyone noticing, payments get collected but never properly tracked, and staff need different levels of access to the system. Most gym owners I spoke to were doing all of this with WhatsApp groups and Excel sheets.

I wanted to build something real and practical — not a bloated SaaS with features nobody uses, but a focused tool that a gym owner and their 2–3 staff members could pick up and use daily without training. The result is FitKalp CRM: a full-stack gym management platform handling members, subscriptions, payments, attendance, expenses, invoices, analytics, equipment, and more.

The Stack and Why I Chose It

Next.js 14 (App Router) — The gym dashboard involves a lot of data: active members, expiring subscriptions, revenue, expenses. With React Server Components, I fetch all of that on the server and stream the UI progressively — no extra client-side API round trips for the initial render. This made the dashboard feel fast without any manual caching tricks.

TypeScript — Non-negotiable. With roles, permissions, subscription statuses, and financial calculations, strict types are what keep bugs out of production.

PostgreSQL + Prisma — Relational data fits gym management perfectly. Prisma gives type-safe queries and migration history. More importantly, Postgres supports Row-Level Security (RLS), which I use for multi-tenancy.

Auth.js (NextAuth v5) — Credentials-based login with JWT sessions. Role and gym context live directly in the JWT token.

Tailwind CSS + shadcn/ui-style components — Fast to iterate, looks professional, easy to maintain.

Supabase — Postgres hosting and Storage for file uploads (logos, member photos).

Resend & Fast2SMS — Transactional email with PDF receipts attached, and SMS notifications for Indian numbers.

Puppeteer + @sparticuz/chromium — PDF generation for invoices and receipts within serverless limits.

Recharts — Responsive charts in the analytics and dashboard sections.

System Architecture & Visual Infographics

To clearly map out every architectural decision, operational engine, and security boundary across the system, I designed a suite of 5 visual-first Excalidraw infographics. Each diagram condenses complex full-stack concepts into clean visual flows (Problem → Cause → Impact → Solution):

• 01-system-architecture-and-dual-auth: Dual-Runtime Authentication with Edge Middleware route guards vs Node.js Server Actions & decoupled HMAC member sessions.
• 02-multi-tenancy-and-rls-isolation: Multi-Tenant Data Sovereignty eliminating PgBouncer connection pool bleed using transaction-scoped GUCs (SET LOCAL) and Postgres RLS.
• 03-gym-operations-and-lifecycle: Operational Lifecycle with reception QR intake, atomic ACID enrollment, and derived anti-stale subscription status.
• 04-finance-and-pdf-pipeline: Financial Ledger & Document Engine with native split payment math, 3-tier invoice branding fallback, and serverless Chromium PDF rendering.
• 05-saas-tiering-and-entitlements: Commercial Tiering & Super Admin with 3 SaaS tiers, 14 granular entitlement flags, and pure-function in-memory resolvers.

Multi-Tenancy: How Multiple Gyms Share One Database

This is the most important architectural decision in the project.

FitKalp is a SaaS product — multiple gyms share the same database, but each gym must see only its own data. I implemented this using PostgreSQL Row-Level Security (RLS). Every gym-scoped table has a gymId column, and Postgres RLS policies at the database level enforce isolation.

The tricky part is Supabase's connection pooler (PgBouncer) running in transaction mode. Session-level GUC variables (SET app.gym_id) don't survive transaction boundaries and bleed into other pooled sockets. So if you set it once at the connection level, the next query from a different gym might slip through.

My solution is the withTenant function:

Infographic 02 — Multi-Tenancy & RLS IsolationClick to zoom

Click to inspect

export function withTenant<T>(
  gymId: string,
  fn: (tx: Prisma.TransactionClient) => Promise<T>
): Promise<T> {
  return withDbContext({ kind: "tenant", gymId }, fn);
}

Authentication: Two Configs for Two Runtimes

I use Auth.js v5 (NextAuth) with a credentials provider.

The challenge: Next.js middleware runs on the Edge runtime, which doesn't support Node.js modules like Prisma or bcrypt. If I put everything in one auth config file, the middleware would fail to import it.

The solution is to split auth into two files:

Infographic 01 — System Architecture & Dual-Runtime AuthClick to zoom

Click to inspect

• auth.config.ts — edge-safe. Contains route protection logic, JWT/session callbacks, no Prisma, no bcrypt. The middleware imports only this.
• auth.ts — full Node.js. Contains the credentials provider that does the actual DB lookup and bcrypt comparison. Server actions import this.

Role-Based Access: Three Roles, Central Enforcement

There are three staff roles: Owner, Admin, and Staff. All permission logic is centralised in permissions.ts:

export function canViewFinancials(role: Role): boolean {
  return role === "OWNER";
}
export function canManagePackages(role: Role): boolean {
  return role === "OWNER" || role === "ADMIN";
}
export function canManageMembers(role: Role): boolean {
  return role === "OWNER" || role === "ADMIN" || role === "STAFF";
}

The server is the source of truth. Every server action and API route checks permissions before executing. The UI mirrors these checks to hide buttons — but that's only UX, never security. A missing button on the client means nothing if the server doesn't also enforce it.

Member Management & Operations Lifecycle

Atomic Onboarding, Derived Statuses, and QR Check-ins

Adding a member creates three things at once: the member record, their first subscription (package + start/end dates), and optionally an initial payment. I handled this in a single server action wrapped in withTenant, so either everything commits or nothing does. No partial states.

Subscription status is computed dynamically at read time from the endDate:

Infographic 03 — Operational Lifecycle & State EnginesClick to zoom

Click to inspect

• Active (🟢) — more than 7 days remaining.
• Expiring Soon (🟡) — within the next 7 days, with 1-click WhatsApp renewal action.
• Expired (🔴) — end date has passed.

I deliberately never store a status field in the database. Stored status gets stale — if you store 'Active' and a cron job fails, members stay Active forever. By computing from endDate on every read, the status is mathematically guaranteed to be accurate.

For check-ins, each member receives a unique revokable token encoded into a QR code. When scanned at the front desk, the token is verified and attendance is recorded instantly with zero manual typing.

Finance Module, Custom Invoicing & Serverless PDF Pipeline

Payments are always linked to a subscription. You record amount, method (Cash, UPI, Card, Bank Transfer, Cheque), and an optional note. The system tracks priceAtPurchase, totalPaid, and derives pendingAmount — allowing split installments and partial payments naturally.

For invoices, gym owners need their custom logo, colors, signature, and payment terms on every document. I designed a 3-tier fallback template system with Prisma JSON columns and bundled Puppeteer with @sparticuz/chromium to generate PDFs inside serverless memory limits (<50MB stripped binary).

Infographic 04 — Financial Ledger & PDF PipelineClick to zoom

Click to inspect

model InvoiceTemplate {
  templateId      Int       // 1 or 2 (design layout)
  branding        Json?     // { logoUrl, primaryColor }
  defaultSettings Json?     // { defaultTerms, signature, paymentInformation }
  isDefault       Boolean
}

Member Self-Service Portal & Decoupled Auth

The member portal (/member) uses a completely separate auth system from the staff area. Members don't have accounts in the User table — they authenticate with their member credentials (phone + password or member number + PIN).

I implemented a custom HMAC-signed cookie session with SHA-256 and verified with crypto.timingSafeEqual on every request to prevent timing attacks:

export function createMemberToken(payload: MemberSessionPayload): string {
  const data = Buffer.from(JSON.stringify(payload)).toString("base64url");
  const signature = signPayload(data);  // SHA-256 HMAC
  return `${data}.${signature}`;
}

This guarantees that member traffic is cleanly isolated from staff JWT sessions, with zero risk of privilege escalation.

SaaS Tier System & Commercial Pricing

Different gyms get different features based on their subscription plan across three tiers (Starter, Growth, Scale):

Instead of checking plan names with fragile if (plan === 'GROWTH') statements, access is decomposed into 14 granular entitlement keys (members, staff_accounts, payments, attendance, visitor_crm, invoices, advanced_analytics, expense_tracking, notifications, advanced_finance, equipment, maintenance, custom_branding, public_portal).

The entitlement resolver is a pure in-memory function that evaluates gym account state, temporary manual overrides, and plan bundles with zero cache drift.

Architectural Decision: SaaS Entitlements, Pure Resolver & Super Admin

Infographic 05 — Commercial Tiering & Super AdminClick to zoom

Click to inspect

Key Technical Learnings & Closing

Design your data model before writing UI: Getting the subscription-payment relationship right took three iterations, but saved dozens of hours downstream.

Server Components eliminate frontend data-fetching boilerplate: The App Router fetches server data directly, eliminating useEffect loading spinners and client-side waterfall requests.

RLS requires strict transaction management: The withTenant wrapper solves connection pool bleed at the database kernel level.

Permission checks belong on the server: UI button hiding is UX; every server action must independently verify claims.

Notification failures must never roll back core transactions: Best-effort notifications in isolated error boundaries protect the primary database state.

“FitKalp CRM is a complete, production-ready gym management system. It's not trying to do everything — it's trying to do the right things, with proper engineering reasoning behind each decision.”