Server-Side System Architecture (NestJS Backend)

Executive Summary

The Learnille Server (server/) is an enterprise-grade NestJS RESTful API backend engineered for multi-tenant online learning, 1-on-1 expert consultations, real-time presence, wallet payouts, and multi-currency transaction processing.

🏛 1. High-Level Server System Diagram

                                      +------------------------------------+
                                      |   Client Apps (Student, Admin,     |
                                      |      Instructor, Consultant)       |
                                      +-----------------+------------------+
                                                        |
                                           HTTPS / REST / WebSockets
                                                        |
                                                        v
+---------------------------------------------------------------------------------------------------+
|                                 NESTJS SERVER BACKEND (`server/`)                                 |
|                                                                                                   |
|  +---------------------------------------------------------------------------------------------+  |
|  | ENTRY PIPELINE: Helmet -> Cors -> CookieParser -> ThrottlerGuard -> RequestLoggerMiddleware |  |
|  +----------------------------------------------+----------------------------------------------+  |
|                                                 |                                                 |
|  +----------------------------------------------v----------------------------------------------+  |
|  | GLOBAL INTERCEPTORS & FILTERS: ResponseInterceptor, AllExceptionsFilter, CurrencyConversion  |  |
|  +----------------------------------------------+----------------------------------------------+  |
|                                                 |                                                 |
|  +----------------------------------------------v----------------------------------------------+  |
|  | FEATURE MODULE DOMAINS:                                                                      |  |
|  | - AuthModule (JWT RS256, Passport, Google/Apple OAuth, CASL RBAC)                            |  |
|  | - CourseModule (Curriculum Editor, Sections, Video Progress)                                 |  |
|  | - ConsultationModule (Availability Calendar, Booking Engine, Slot Resolution)              |  |
|  | - WalletModule & WithdrawalModule (Escrow Hold, NGN Bank Resolution, OTP Verification)       |  |
|  | - ProductModule & ValidationModule (Quality Assurance Queue, State Machine)                  |  |
|  | - PaymentModule (Paystack & Flutterwave Gateways, Webhook Verification)                      |  |
|  | - OpenSearchModule (Vector Indexing, Full-Text Catalog Search)                               |  |
|  | - InstantdbModule (Real-Time Room State & Sync)                                              |  |
|  | - OutboxModule & BullmqModule (Transactional Outbox Pattern, Async Queues)                   |  |
|  | - NotificationModule (Novu Framework & Soketi WebSocket Channels)                            |  |
|  +----------------------------------------------+----------------------------------------------+  |
+-------------------------------------------------|-------------------------------------------------+
                                                  |
       +--------------------+---------------------+--------------------+--------------------+
       |                    |                     |                    |                    |
       v                    v                     v                    v                    v
+--------------+     +--------------+     +--------------+     +--------------+     +--------------+
| Self-Hosted  |     | Self-Hosted  |     | Cloudflare   |     | OpenSearch   |     | New Relic    |
|  PostgreSQL  |     |    Redis     |     |   R2 S3      |     | Index Engine |     | APM & Logs   |
| (TypeORM DB) |     |  (BullMQ)    |     |  (Storage)   |     | (Vector Srch)|     | & Sentry     |
+--------------+     +--------------+     +--------------+     +--------------+     +--------------+

🛠 2. Request Handling Pipeline & Lifecycle

When an HTTP request enters the NestJS server, it passes through a deterministic processing chain:

[ Incoming HTTP Request ]
       |
       v
1. [ Security & Middleware Layer ]
   - Helmet (Security headers)
   - Cookie Parser
   - AppRequestLoggerMiddleware (Pino/Winston request logger)
       |
       v
2. [ Rate Limiting Guard ]
   - ThrottlerGuard (Redis-backed rate limiting with RedisThrottlerStorage)
       |
       v
3. [ Authentication & Authorization Guards ]
   - JwtAuthGuard (Passport JWT RS256/HS256 validation)
   - RolesGuard / CASL AbilityGuard (Role checks: STUDENT, INSTRUCTOR, CONSULTANT, ADMIN)
       |
       v
4. [ DTO Input Validation Pipe ]
   - ValidationPipe (class-validator DTO checking with transform: true)
       |
       v
5. [ Controller Action Handler ]
   - Extracts payload via @Body(), user via @CurrentUser()
   - Delegates business logic to domain service
       |
       v
6. [ Interceptors & Exception Filters ]
   - CurrencyConversionInterceptor (converts prices dynamically via dynamic header)
   - ResponseInterceptor (wraps output into standard { statusCode, message, data } JSON)
   - AllExceptionsFilter (catches and formats HTTP and system errors for client & Sentry)
       |
       v
[ Formatted HTTP Response ]

📦 3. Deep Domain Module Architecture

3.1. Authentication & Security Subsystem (`auth/`, `casl/`, `crypto/`)

Token Architecture: RS256 asymmetric key pairs (CryptoModule). Short-lived JWT access tokens + Redis-rotated refresh tokens.
Social Login: OAuth flow handling for Google (google/) and Apple (auth/). Account linking endpoints permit attaching social credentials to an existing user account.
CASL Role Permissions: Fine-grained access control supporting 4 primary roles (Student, Instructor, Consultant, Admin).

3.2. Course Curriculum Engine (`course/`, `category/`)

Normalized Curriculum: Supports hierarchical structure: Course -> Section -> Subsection -> Item (Video, Document, Quiz).
Progress Tracking: Continuous video timestamp tracking via heartbeat endpoints (/course/video-progress) recalculating student completion percentage dynamically.
Category Hierarchy: Category tree mapping supporting parent-child categories, featured flags, and display order batch updating.

3.3. Consultation Booking & Availability (`consultation/`, `consultant/`)

Dual Mode: Supports ONEOFF (specific single date/time) and RECURRING (weekly interval windows) consultations.
Availability Engine: Calculates available time slots dynamically by cross-referencing consultant weekly hours, booked slot reservations, minimum notice buffers (e.g. 2 hours notice required), and timezone offsets.
Reschedule Workflow: The owning consultant can prompt a student to reschedule a missed session. The student selects the replacement time and pays any applicable fee; the owning consultant or an admin approves. Repeat purchases create separate bookings. See Consultation rescheduling and rebooking.

3.4. Escrow, Wallet & Withdrawal System (`wallet/`, `withdrawal/`, `payments/`)

Escrow Payment Hold: Funds from course sales or bookings enter pending_hold in provider wallets, releasing to available_balance upon course refund window expiry or consultation completion.
Dual Payment Gateways: Paystack and Flutterwave adapters with strict webhook signature verification (x-paystack-signature, Flutterwave hash).
Multi-Step Withdrawal Flow:
1. Add bank account method (/withdrawals/methods). Bank account holder name is resolved via Flutterwave NGN lookup.
2. Verify account via SMS/email OTP (/withdrawals/methods/verify).
3. Initiate withdrawal request (/withdrawals/request).
4. Verify withdrawal with secondary OTP (/withdrawals/:id/verify).
5. Admin approves and executes automated bank payout (/withdrawals/:id/approve).

3.5. Transactional Outbox & Background Processing (`outbox/`, `bullmq/`)

Outbox Pattern: Changes to database entities write an outbox event in the same DB transaction (outbox_events).
BullMQ Workers: BullMQ worker polls and processes outbox events asynchronously, handling external webhook dispatches, email triggers via Novu, and real-time Soketi broadcasts with automatic retries and dead-letter queues.

3.6. Search & Vector Engine (`opensearch/`)

Catalog Indexing: Auto-indexes published courses and consultations into OpenSearch.
Vector Search: Supports hybrid keyword search and semantic vector embeddings for recommendations and fast discovery.

🗄 4. Database & Persistence Standards

Primary Database: PostgreSQL accessed via TypeORM.
Naming Standard: All database columns use snake_case transformation (created_at, user_id, is_published).
Migrations: TypeORM migration scripts (server/src/migrations/) maintain database schema changes. Direct schema alteration in production is strictly prohibited.

📊 5. Server Configuration & Observability

Centralized Config: ConfigModule validates all environment variables on boot via validateConfig in server/src/config.ts.
Monitoring: Integrated with New Relic APM for transaction tracing, New Relic Log Enrichment for Winston logs, and Sentry for real-time exception reporting.
Health Diagnostics: HealthModule powered by NestJS Terminus monitoring DB connection status, Redis availability, and host memory usage (/health).

Course certificate lifecycle

The certificate module validates course completion, fills the supplied PDF template, persists an immutable private certificate and queues its completion email through the transactional outbox.

Getting started

Company

Product

Design

Engineering

DevOps

Security and compliance

Audit

Team and process

Operations

People

Policies

Documentation governance

Templates

Server-Side System Architecture (NestJS Backend)

Executive Summary

🏛 1. High-Level Server System Diagram

🛠 2. Request Handling Pipeline & Lifecycle

📦 3. Deep Domain Module Architecture

3.1. Authentication & Security Subsystem (`auth/`, `casl/`, `crypto/`)

3.2. Course Curriculum Engine (`course/`, `category/`)

3.3. Consultation Booking & Availability (`consultation/`, `consultant/`)

3.4. Escrow, Wallet & Withdrawal System (`wallet/`, `withdrawal/`, `payments/`)

3.5. Transactional Outbox & Background Processing (`outbox/`, `bullmq/`)

3.6. Search & Vector Engine (`opensearch/`)

🗄 4. Database & Persistence Standards

📊 5. Server Configuration & Observability

Course certificate lifecycle

Executive Summary

🏛 1. High-Level Server System Diagram

🛠 2. Request Handling Pipeline & Lifecycle

📦 3. Deep Domain Module Architecture

3.1. Authentication & Security Subsystem (auth/, casl/, crypto/)

3.2. Course Curriculum Engine (course/, category/)

3.3. Consultation Booking & Availability (consultation/, consultant/)

3.4. Escrow, Wallet & Withdrawal System (wallet/, withdrawal/, payments/)

3.5. Transactional Outbox & Background Processing (outbox/, bullmq/)

3.6. Search & Vector Engine (opensearch/)

🗄 4. Database & Persistence Standards

📊 5. Server Configuration & Observability

Course certificate lifecycle

3.1. Authentication & Security Subsystem (`auth/`, `casl/`, `crypto/`)

3.2. Course Curriculum Engine (`course/`, `category/`)

3.3. Consultation Booking & Availability (`consultation/`, `consultant/`)

3.4. Escrow, Wallet & Withdrawal System (`wallet/`, `withdrawal/`, `payments/`)

3.5. Transactional Outbox & Background Processing (`outbox/`, `bullmq/`)

3.6. Search & Vector Engine (`opensearch/`)