Accessa
A comprehensive backend system developed as a contract project for gym management and bill payment. It handles role-based access control, complex membership lifecycles, and automated fiscal receipt generation in compliance with local regulations.
Overview
Accessa is a robust gym management and bill payment platform built as a contract project to streamline complex facility operations. The system serves as the technical backbone for role-based access control, membership lifecycle management, fiscal compliance, and QR code integrations.
The Problem
Gym operations involve complex, interconnected domains including granular permission management, strict membership pause policies, and real-time fiscal receipt webhooks that require high reliability and strict transactional integrity to prevent data inconsistencies.
The Solution
Built a highly scalable Fastify API using Prisma and PostgreSQL. Implemented tiered access levels for permissions, decoupled slow network operations from database transactions to prevent timeouts, and built robust webhook handlers with strict sanitization for fiscal integrations.
Design Flow
Role-Based Access Control
Permission mapping
Membership Lifecycle
Pause Rule Validation
Payment Integration
Processing & Error Handling
Decoupling of external API calls from DB transactions
Schema Design
Designed a modular, multi-tenant relational schema using Prisma. It features a dual-scope RBAC system separating Platform vs Gym permissions down to the action/resource level. The financial core utilizes a BigInt-backed immutable ledger with triple-balance wallets (Available, Pending, Locked) to manage split payments and webhook settlements accurately. Membership lifecycles act as strict state machines, specifically tracking multi-step approval workflows for membership pauses and grace periods, ensuring perfect auditability.
Technical Decisions
Fastify for high-performance API routing. Prisma ORM for type-safe database queries. PostgreSQL for reliable relational data storage. Zod for strict request payload validation. Jest for comprehensive unit and integration testing. Separation of external API calls from interactive DB transactions.
Challenges
Handling Prisma transaction timeouts during slow operations like QR code generation. Syncing and casting complex webhook data from Alanube fiscal receipts. Managing granular gym permissions while keeping the API payloads simple. Enforcing strict membership pause rules without running into N+1 query issues.
Key Learnings
Network-bound operations should never be placed inside interactive DB transaction blocks. Strict payload sanitization and date parsing is critical for stable webhook handling. Mapping granular DB actions to high-level access tiers simplifies role management significantly.
Results
A highly performant and stable backend API. Eliminated transaction timeouts by optimizing Prisma queries. Robust fiscal compliance integration matching DGII regulations. Seamless and scalable gym membership and permission management flows.