> ## Documentation Index
> Fetch the complete documentation index at: https://ihub.learnille.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Server-Side System Architecture (NestJS Backend)

> Migrated from the previous Learnille internal documentation hub

## 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](https://ihub.learnille.com/engineering/architecture/consultation-rescheduling-and-rebooking.md).

### 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](https://ihub.learnille.com/engineering/architecture/course-certificates.md) validates course completion,
fills the supplied PDF template, persists an immutable private certificate and
queues its completion email through the transactional outbox.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.