System Architecture Overview

Overview

Learnille is architected as a modular, package-decoupled digital learning platform. It isolates backend REST API logic, real-time sync, background job workers, search indexing, media storage, and frontend client applications into focused packages, designed for self-hosted infrastructure.

• 🏛 Server-Side Architecture (NestJS Backend) - Deep architecture specification of the NestJS backend API, pipeline, request lifecycle, outbox pattern, and domain modules.
• 📐 System Architecture Diagram - 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	Self-Hosted PostgreSQL, 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	OpenSearch / Elasticsearch	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.