Roomfit
A room, property, and roommate marketplace supported by a versioned NestJS backend serving web and mobile clients with real-time messaging and Paystack billing.
PRODUCT & DOMAIN CONTEXT
Roomfit connects house seekers, property listers, and potential roommates across Nigeria. It allows users to post available spaces, search for compatible roommates based on lifestyle preferences, communicate in real time, and upgrade to Premium access for verified publishing privileges.
THE CORE ENGINEERING PROBLEM
Roomfit needed a single, robust backend to coordinate two separate client apps (React Native mobile and Next.js web), enforce listing lifecycle rules, manage real-time user chat, handle Paystack payments, and gate Premium listing visibility without relying on frontend state for authorization or access checks.
SYSTEM ARCHITECTURE MAP
Data Flow & Boundary Topology
Client requests from mobile (React Native) and web (Next.js) pass through NestJS controller guards. Business logic invokes Prisma ORM to interact with PostgreSQL, while Socket.IO manages real-time socket sessions. Paystack webhooks update subscription records asynchronously.
Mobile Client (Bearer Token)
Web Client (HTTP Cookies)
REST & Socket.IO Gateway
Prisma ORM Persistence
Session & Rate Limit Store
Payment & Webhooks
Push & Transactional Mail
Integration Boundaries & Protocols
SYSTEMS & SERVICES BUILT
Core Backend Modules & Responsibility
Modular NestJS Core & API Gateway
Structured domain modules (Auth, Users, Listings, Messaging, Payments, Moderation) with strict DTO validation, global exception filters, and client-tailored response transformers.
Listing Lifecycle & Publishing Engine
A state machine managing Draft -> Pending Review -> Published -> Expired states. Enforces quota limits and subscription status prior to publishing.
Paystack Payment & Subscription Handler
Handles checkout creation, HMAC-SHA512 webhook signature validation, idempotency checks on transaction IDs, subscription renewal status, and automatic grace period management.
Real-Time Messaging Gateway
Socket.IO gateway handling room authorization, message persistence to PostgreSQL, delivery receipts, and fallback push notifications for offline recipients.
Detailed Technical Responsibilities
- •Designed and implemented modular NestJS REST APIs serving both mobile (bearer token) and web (cookie/session) clients.
- •Engineered the complete listing lifecycle including drafts, validation rules, media uploads, location indexing, and publication gating.
- •Integrated Socket.IO for private real-time messaging, unread counts, and active state synchronization.
- •Built Paystack payment processing for one-time and recurring Premium subscriptions, signed webhook verification, callback reconciliation, and access expiry management.
- •Developed user management features: profile customization, roommate matching preferences, reviews, reports, and push/email notification triggers.
ENGINEERING DECISIONS & TRADE-OFFS
Architectural Choices & Rationale
Server-Authoritative Subscription & Access Logic
Slightly higher backend database query overhead on authenticated request guards, mitigated with short-lived Redis caching.
Modular Monolith with NestJS Modules
All services share compute resources; high chat throughput could impact API performance if not scaled properly.
Dual Authentication Strategy (Cookie vs Bearer)
Required explicit guard logic in NestJS to seamlessly parse and validate both token delivery mechanisms.
RELIABILITY & SAFETY MECHANISMS
- •HMAC-SHA512 webhook signature verification ensuring all payment events originate strictly from Paystack IP ranges.
- •Idempotent transaction processing using unique Paystack reference keys to prevent duplicate subscription crediting.
- •Database soft-deletes and audit logging for listing moderation and user safety reports.
- •Automatic graceful degradation for Socket.IO disconnects with automatic fallback to push notifications.
CHALLENGES & RESOLUTION
When users completed payment, the client redirect often arrived at the backend before the Paystack webhook webhook fired. Solved by implementing an active verification polling endpoint that checks Paystack directly if local status is still pending.
Roommate and listing queries involved multiple filters (budget, gender preference, lifestyle tags, location). Optimized PostgreSQL query indexing with Prisma raw filters and composite indexes on active status and location fields.
VERIFIED OUTCOMES
- •Built one backend contract serving both the web and mobile product surfaces.
- •Implemented webhook-backed Premium subscription provisioning and reconciliation for the main billing flow.
- •Improved listing discovery responsiveness through query tuning and indexing work.
NEXT SYSTEM IMPROVEMENTS
- •Implement Elasticsearch / Meilisearch for ultra-fast full-text search across listing descriptions.
- •Introduce background queue worker (BullMQ / Redis) for async email/push notification dispatches.
Interested in discussing this architecture or an open backend role?
Reach out via email or review my full experience on my resume.