> ## 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.

# System Architecture Overview

> Migrated from the previous Learnille internal documentation hub

## Overview

Learnille is architected as a modular, package-decoupled digital learning platform. It isolates backend REST API logic, real-time sync, background job workers, OpenSearch indexing, media storage, and frontend client applications into focused packages. Production uses Dokploy and managed data providers where documented in the deployment guide.

* 🏛 **[Server-Side Architecture (NestJS Backend)](https://ihub.learnille.com/engineering/architecture/server-architecture.md)** - Deep architecture specification of the NestJS backend API, pipeline, request lifecycle, outbox pattern, and domain modules.
* 📐 **[System Architecture Diagram](https://ihub.learnille.com/engineering/architecture/system-architecture-diagram.md)** - Visual block diagrams and component breakdown.

***

## 🏗 Architecture Components

```
+-----------------------------------------------------------------------------------+
|                                FRONTEND PORTALS                                   |
|  +--------------------+  +--------------------+  +-----------------------------+  |
|  |   Student Web      |  | Instructor Portal  |  | Consultant & Admin Portals  |  |
|  |  (Vite+React+TS)   |  |  (Vite+React+TS)   |  |      (Vite+React+TS)       |  |
|  +---------+----------+  +---------+----------+  +--------------+--------------+  |
+------------|-----------------------|----------------------------|-----------------+
             |                       |                            |
             +-----------------------+----------------------------+
                                     |
                                REST API & WebSocket Connections
                                     |
                                     v
+-----------------------------------------------------------------------------------+
|                            NESTJS SERVER BACKEND API                              |
|  +-----------------------------------------------------------------------------+  |
|  | Controllers: Auth, User, Course, Consultation, Wallet, Validation, Analytics|  |
|  | Guards: JwtAuthGuard, RolesGuard, CASL Ability                              |  |
|  | Interceptors: TransformInterceptor, TimeoutInterceptor, LoggingInterceptor  |  |
|  +-----------------------------------------------------------------------------+  |
+------+---------------+---------------+---------------+---------------+------------+
       |               |               |               |               |
       v               v               v               v               v
+--------------+ +-----------+ +---------------+ +-----------+ +---------------+
|  PostgreSQL  | | InstantDB | |  Soketi / WS  | |  BullMQ   | |  OpenSearch   |
| (Self-Hosted | | (Realtime | | (Notification | |  (Queues  | | (Search Vector|
|  TypeORM DB) | |   State)  | |  Websockets)  | | & Outbox) | |   Indexing)   |
+--------------+ +-----------+ +---------------+ +-----------+ +---------------+
```

***

## 🛠 Technology Stack Breakdown

| Layer / Subsystem | Primary Technologies | Purpose |
| :- | :- | :- |
| **Backend Framework** | NestJS (TypeScript), Passport JWT | RESTful API, DTO validation, Modular business logic |
| **Primary Database** | Neon PostgreSQL in production, Aiven PostgreSQL in development, TypeORM | Relational persistence (Users, Courses, Bookings, Transactions) |
| **Real-time State Sync** | InstantDB | Real-time state synchronization for active sessions, presence, and chat |
| **WebSocket Broadcast** | Soketi (Pusher protocol) | Live push notifications and real-time UI counters |
| **Background Queues** | BullMQ, Redis | Async jobs (Email delivery, outbox event processing, media transcode) |
| **Search Engine** | Aiven OpenSearch | Course catalog indexing, full-text search, and recommendations |
| **Object Storage** | Cloudflare R2 (S3 API) / MinIO | Video asset storage, thumbnails, attachments, zero-egress fee storage |
| **Monitoring & Logging** | New Relic APM & Logs, Sentry | Application performance monitoring, log aggregation, exception tracking |
| **Notifications** | Novu | Multi-channel notification pipeline (Email, Push, In-App) |
| **Payment Gateways** | Paystack, Flutterwave | Multi-currency card payments, mobile money, and NGN/USD bank payouts |
| **Frontend Framework** | React 18, Vite, TypeScript | Fast SPA client applications (`student`, `instructor`, `admin`, `consultant`) |
| **UI Components** | Chakra UI, CSS Variables | Responsive visual design system and component UI |

***

## 📌 Architectural Guarantees & Guardrails

1. **Package Separation**: Type definitions cannot be cross-imported between child package folders. Types must be defined within their respective package or shared via explicit boundaries.
2. **Database Naming**: PostgreSQL entities use `snake_case` column naming transformations.
3. **Controller Security**: All controllers are protected by `JwtAuthGuard`. Authenticated user context is accessed exclusively via `@CurrentUser()`.
4. **Validation Enforcement**: All incoming payload data must be validated using explicit DTOs with `ValidationPipe`.


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