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, 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) - 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	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

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.
Database Naming: PostgreSQL entities use snake_case column naming transformations.
Controller Security: All controllers are protected by JwtAuthGuard. Authenticated user context is accessed exclusively via @CurrentUser().
Validation Enforcement: All incoming payload data must be validated using explicit DTOs with ValidationPipe.

Getting started

Company

Product

Design

Engineering

DevOps

Security and compliance

Audit

Team and process

Operations

People

Policies

Documentation governance

Templates

System Architecture Overview

Overview

🏗 Architecture Components

🛠 Technology Stack Breakdown

📌 Architectural Guarantees & Guardrails