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

# Software Architecture Document: Learnille Server

> Migrated from the previous Learnille internal documentation hub

## 1. Introduction

1.1. Purpose
1.2. Scope
1.3. Definitions, Acronyms, and Abbreviations
1.4. References
1.5. Overview of the Remainder of the Document

## 2. Architectural Representation

2.1. Architectural Goals

* Modularity: Achieved through NestJS modules for distinct features.
* Scalability: Leveraging technologies like Node.js, PostgreSQL, Redis, and BullMQ.
* Maintainability: TypeScript for type safety, consistent structure via NestJS.
* Security: JWT-based authentication, role-based access control (CASL observed), Helmet for security headers.
* Testability: Structure supports unit, integration, and e2e testing (Jest setup observed).
  2.2. Constraints
* Technology Stack: Primarily NestJS (Node.js/TypeScript), PostgreSQL, Redis.
* Reliance on specific third-party services (e.g., Paystack, Novu, Sentry, New Relic, Cloudflare R2 / S3, InstantDB/Triplit, ClickHouse, Shlink).
  2.3. Key Architectural Decisions & Rationale
* Choice of NestJS: Provides a robust, modular framework for building scalable server-side applications with TypeScript.
* Modular Design: Enhances separation of concerns, maintainability, and team collaboration.
* Use of TypeORM: Offers a powerful ORM for database interaction with PostgreSQL.
* JWT for Authentication: Standard and stateless approach for API security.
* Asynchronous Processing with BullMQ: For handling background tasks and improving responsiveness.
* Centralized Configuration: Using `@nestjs/config` with environment-specific files and Joi validation.
* Event-Driven Elements: Use of `@nestjs/event-emitter` for decoupling components.

## 3. System Overview and Context

3.1. System Context Diagram
(Conceptual - to be described textually for now)
The Learnille Server acts as the central backend API for various clients (web application, mobile applications). It interacts with:

* Databases: Neon PostgreSQL in production and Aiven PostgreSQL in development, Redis Cloud, Aiven OpenSearch, and self-hosted InstantDB.
* Payment Gateways: Paystack, Flutterwave.
* Notification Service: Novu.
* Error Tracking & Monitoring: Sentry, New Relic.
* File Storage: Cloudflare R2 (S3 API compatible) / MinIO.
* Authentication: Google & Apple (for social login).
* URL Shortening: Shlink.
  3.2. Major Components
* API Layer: Exposes RESTful endpoints (NestJS Controllers).
* Application Core: Business logic encapsulated in NestJS Services and Modules.
* Data Access Layer: TypeORM repositories interacting with databases.
* Infrastructure Services: Wrappers or integrations for Redis, BullMQ, OpenSearch, Novu, New Relic, Sentry, etc.
* External Service Integrations: Clients/SDKs for Paystack, Flutterwave, Google, Cloudflare R2, etc.

## 4. Architectural Views

4.1. Logical View / Module View
4.1.1. Overview
The application is structured as a set of NestJS modules. A root `AppModule` imports core infrastructure modules and feature-specific modules.

```mermaid theme={null}
graph LR
    subgraph User Interaction
        UI(Frontend)
    end

    subgraph Backend API (NestJS)
        subgraph Core Modules
            AppMod(AppModule) --> Cfg(ConfigModule)
            AppMod --> DB(DatabaseModule)
            AppMod --> Auth(AuthModule)
            AppMod --> Redis(RedisModule)
            AppMod --> Bull(BullMQModule)
            AppMod --> OpenSearch(OpenSearchModule)
            AppMod --> Notify(NotificationModule)
            AppMod --> Common(Common Utils)
        end

        subgraph Feature Modules
            Market(MarketplaceModule) -- uses --> Elastic
            Consult(ConsultationModule) -- uses --> User(UsersModule)
            Consult -- uses --> Timeslot(TimeslotService)
            Consult -- triggers --> Pay(PaymentModule)
            Cart(CartModule) -- holds --> ConsultEntity(Consultation Entity)
            Cart -- holds --> CourseEntity(Course Entity)
            Pay -- uses --> User
            Pay -- uses --> PayGW(PaystackModule)
            Pay -- updates --> Wallet(WalletService)
            Pay -- triggers --> Enroll(EnrollmentModule)
            Pay -- triggers --> Notify
        end
    end

    UI --> Market
    UI --> Consult
    UI --> Cart
    Market --> Consult
    Consult --> Pay
    Cart --> Pay # Assumed Checkout Flow
```

4.1.2. Core Infrastructure Modules

* `ConfigModule`: Manages environment variables and application configuration with Joi validation.
* `DatabaseModule` (custom, likely wraps `TypeOrmModule`): Manages PostgreSQL database connections and entity registration.
* `AuthModule`: Handles authentication (JWT, local, Google), authorization strategies, and user session management.
* `CryptoModule`: Provides cryptographic functions (password hashing, JWT signing/verification).
* `RedisModule`: Manages Redis connections for caching and potentially other uses (e.g., Throttler storage).
* `BullmqCustomModule`: Manages BullMQ for background job processing.
* `OpenSearchModule`: Integrates with OpenSearch for search capabilities.
* `NotificationModule` & `NovuModule`: Manages notifications via Novu (workflows, subscribers).
* `SentryModule`: Integrates Sentry for error tracking and performance monitoring.
* `MailerModule`: Handles email sending via SMTP with Handlebars templating.
* `ClickHouseModule`: Integrates ClickHouse for analytics.
* `StorageModule` (with `SimpleStorageService`): Manages file storage (e.g., S3).
* `LoggerModule` (nestjs-pino) / Winston: Provides structured logging capabilities.
* `TerminusModule`: For health checks.
* `ThrottlerModule`: For API rate limiting.
* `EventEmitterModule`: For in-application event handling.
  4.1.3. Key Feature Modules (Initial list based on analysis)
* `UsersModule`: Manages user profiles, roles, and basic user data.
* `CourseModule`: Manages course creation, content (sections, subsections, items), instructors, categories, levels, pricing, and related metadata.
* `ConsultationModule`: Manages consultation offerings, consultant availability (timeslots), user bookings, and individual consultation sessions. It supports different consultation types (e.g., one-off, recurring) and integrates with `ElasticModule` for search, `PaymentModule` for billing, `NotificationModule` for reminders, and `ReviewsModule` for feedback. It has its own set of entities for consultations, bookings, timeslots, and type-specific metadata.
* `PaymentModule`: Orchestrates financial transactions. It integrates with payment gateways (e.g., `PaystackModule`) to process incoming payments for orders. It manages `Payment` entities and includes a `WalletService` and `WalletController` for user fund management and withdrawals. It interacts closely with `OrderModule`, `UsersModule`, `CourseModule`, `ConsultationModule`, and `EnrollmentModule`.
* `PaystackModule`: (If not already listed separately) Provides a dedicated interface for interacting with the Paystack payment gateway API, including payment initiation and webhook handling.
* `InstructorsModule`: Manages instructor-specific profiles, linking them to base `User` accounts. It handles details like professional experience, achievements, expertise, and resume. It's tightly coupled with `UsersModule` and `CourseModule` (as instructors create courses) and interacts with `FilesModule` for resume/profile picture storage and potentially `EnrollmentModule` for viewing course enrollments. It may use a shared `ProviderService` for managing common profile sections like experiences and achievements.
* `ConsultantModule`: Manages consultant-specific profiles, linking them to base `User` accounts. It handles details like professional experience, achievements, expertise, resume, and availability. It's tightly coupled with `UsersModule` and `ConsultationModule` (as consultants offer consultations) and interacts with `FilesModule` for resume/profile picture storage, `ReviewsModule` for feedback, and uses a shared `ProviderService` for managing common profile sections and availability.
* `CartModule`: Provides shopping cart functionality, allowing users to add and manage items (courses, consultations) before purchase. It interacts with product modules for item details and `OrderModule` for checkout.
* `OrderModule`: Manages the order creation process. It takes items (often from a cart), applies coupons, calculates totals, and creates `Order` records. It's a crucial intermediary to `PaymentModule` for initiating transactions and `EnrollmentModule` for post-payment fulfillment.
* `ReviewsModule`: Handles user-submitted reviews and ratings for products (courses, consultations). Interacts with product modules to update aggregate ratings and `EnrollmentModule` for review eligibility. May integrate with `ElasticModule`.
* `MarketplaceModule`: Powers the public-facing discovery of products. Relies heavily on `ElasticModule` for search/filtering and integrates `RecommendationModule`.
* `StudentsModule`: Manages student-specific profiles (linked to `User`) and their interactions, particularly closely tied to `EnrollmentModule`.
* `ImpressionModule`: Tracks user views/interactions with content like courses and consultations, likely feeding data to analytics or recommendation systems.
* `EnrollmentModule`: Manages user enrollment in products, often triggered by successful payments. Includes an `EnrollmentListener` for event-driven enrollment creation and tracks granular progress.
* `CommsModule`: Integrates with third-party communication platforms (e.g., Stream, CometChat) for features like chat/calls, managing user tokens for these services.
* `CategoryModule`: Manages the hierarchical categorization of content (courses, consultations).
* (Others to be detailed as analysis progresses: Product, etc.)
  4.2. Development View
  4.2.1. Source Code Organization: Primarily within `src/`, with modules in dedicated subdirectories (e.g., `src/users`, `src/course`). Common utilities might reside in `src/common` or `src/shared`. Configuration in `src/config.ts` and `env/` directory.
  4.2.2. Key Frameworks and Libraries: NestJS, TypeORM, Express.js (underlying NestJS), Passport.js, Joi, BullMQ, OpenSearch client, Novu SDK, Sentry SDK, Paystack SDK.
  4.2.3. Build Process: `npm run build` (uses `nest build`).
  4.3. Deployment View
  4.3.1. Target Environment(s): Local, Development, Staging, Production (as indicated by `.env` file structure and `NODE_ENV` usage).
  4.3.2. Physical Infrastructure (Conceptual):
* Application Server(s) running Node.js (v22 specified).
* PostgreSQL Database Server.
* Redis Server.
* Aiven OpenSearch service.
* Self-hosted InstantDB server.
* Dependencies on external services (Paystack, Novu, Sentry, Google, S3, Shlink).
  4.3.3. Containerization Strategy: The `server` package is built and run from its Dockerfile through Dokploy in production. Local Docker Compose is used only for development dependencies such as MinIO.
  4.3.4. Technology Stack Summary: Node.js, TypeScript, NestJS, PostgreSQL, Redis, OpenSearch, BullMQ, Novu, Sentry, Paystack, Flutterwave, S3, InstantDB.

## 5. Data Architecture

5.1. Data Persistence Strategy

* Primary Relational Database: PostgreSQL (managed via TypeORM).
* Caching/Session/Rate-Limiting: Redis.
* Search Indexing: OpenSearch.
* Analytics: ClickHouse.
* Real-time/Collaborative Data: Self-hosted InstantDB.
  5.2. High-Level Data Model (Key entities identified so far)
* `User`: Core user information, roles, credentials.
* `Login`: Tracks login sessions/attempts.
* `ForgotPassword`, `VerifyEmail`: Tokens for account recovery/verification.
* `Course`: Main course details, pricing, instructor, category, level.
* `CourseSection`, `CourseSubSection`, `CourseItem`: Hierarchical course content.
* `Instructor`: Profile specific to instructors, linked to a `User`, contains professional details, resume, and courses they manage.
* `Consultant`: Profile specific to consultants, linked to a `User`, contains professional details, resume, availability, and consultations they offer.
* `Student`: Role-specific profiles linked to Users.
* `Consultation`: Main consultation offering details, type, consultant, pricing.
* `Booking`: User bookings for consultations.
* `ConsultationTimeSlot`: Consultant availability.
* `ConsultationSession`: Individual consultation sessions.
* `OneOffConsultationMeta`, `RecurringConsultation`: Metadata for specific consultation types.
* `Payment`: Records of financial transactions, linked to orders, users, and gateways.
* `Withdrawal`: Records of user withdrawal requests from their wallets.
* `Order`: Represents a user's intention to purchase items (courses, consultations).
* `OrderItem`: Represents individual items within an order.
* `Cart`: Represents a user's shopping cart.
* `CartItem`: Represents individual items within a cart.
* `Coupon`, `CouponUsage`: For managing discount codes.
* `Category`: For course categorization.
* `Student`: Profile for student users.
* `Enrollment`, `SectionEnrollment`: Tracks user enrollment and progress in products.
* `Review`: Stores user reviews and ratings.
* `UserAuthTokens` (Comms): Stores tokens for external communication services.
* `File`: For storing references to uploaded files (profile photos, course materials).
* (Others to be added: PaymentTransaction, EnrollmentRecord, Product, etc.)
  5.3. Data Flow for Key Use Cases
* User Registration: Client -> API (`/auth/register`) -> `AuthService` -> `UsersService` (creates User) -> Role-specific service (creates Instructor/Student/Consultant profile) -> DB. Event emitted, Novu notification triggered.
* Course Creation: Client -> API (`/course`) -> `CourseController` -> `CourseService` -> DB (creates Course, links to Instructor, Category, Files, etc.). Event emitted.
* Consultation Booking: User (Client) browses consultations through the OpenSearch-backed marketplace API -> Selects a consultation and an available timeslot -> Submits booking request (API: `POST /consultation/booking`) -> `ConsultationController` -> `ConsultationService` (validates timeslot, creates `Booking` entity, potentially links to `ConsultationSession`) -> Triggers payment flow (via `PaymentModule`) -> On success, confirms booking, sends notifications (via `NovuModule`).
* Checkout Flow: User adds items to Cart (via `CartModule`) -> User proceeds to checkout -> `OrderService` creates an `Order` from Cart items, applies coupons, calculates total, sets status to PENDING -> (Rest of payment flow as previously described, starting with `PaymentsService._initiatePaymentForOrder`).
* Product Discovery: User searches/filters on Marketplace UI -> API (`/marketplace/*`) -> `MarketplaceController` -> `MarketplaceService` -> `OpenSearchModule` -> Returns product list.
* Leaving a Review: User (Student) submits review for a Course -> API (`/review`) -> `ReviewsController` -> `ReviewsService` (validates eligibility, e.g., via `EnrollmentService`) -> Saves `Review` entity -> Updates aggregate rating on `Course` entity.

## 6. Cross-Cutting Concerns

6.1. Security Architecture

* Authentication: JWT-based. `LocalStrategy` for email/password, `GoogleStrategy` for Google OAuth. Managed by `AuthModule` and Passport.js.
* Authorization: Role-based access control (RBAC) implied by `UserRole` and potentially fine-grained with `CaslGuard` (seen in `CourseController`).
* Input Validation: `class-validator` DTOs with `ValidationPipe`.
* HTTP Security Headers: `helmet` middleware.
* CORS: Enabled via `app.enableCors()`.
* Secret Management: Primarily through environment variables (`.env` files, `ConfigModule`). `KEYS_DIR` in config suggests potential for local key storage.
  6.2. Error Handling and Fault Tolerance
* Global Exception Filter: `AllExceptionsFilter` in `main.ts` for standardized error responses.
* Custom exceptions defined per module (e.g., `PhotoNotFoundException` in `UsersModule`).
* Sentry: Integrated for error tracking and reporting (`SentryModule`, process-level handlers in `main.ts`).
  6.3. Logging and Monitoring
* Structured Logging: `nestjs-pino` or Winston (conditional in `main.ts`). `AppRequestLoggerMiddleware` for HTTP request logging.
* Performance Monitoring: Sentry APM (implied by `instrument.ts` and Sentry setup).
* Health Checks: `TerminusModule` imported, likely for `/health` endpoints.
  6.4. Configuration Management
* `@nestjs/config` loading environment-specific `.env` files from `env/`.
* Joi schema validation (`src/config.ts`) for environment variables.
* Type-safe access via `ConfigService` and `Config` interface.
  6.5. API Design
* RESTful principles generally followed.
* Standardized response format via `ResponseInterceptor` (seen in `main.ts`).
* API documentation via Swagger (setup in `main.ts`, available at `/docs`).
  6.6. Asynchronous Processing
* `BullmqCustomModule` for background jobs (e.g., email sending, long computations).

## 7. Design Rationale

7.1. Why NestJS?

* Opinionated framework providing structure for large applications.
* Excellent TypeScript support.
* Modular architecture promotes separation of concerns.
* Built-in support for microservices, testing, and common patterns.
  7.2. Why a Modular Architecture?
* Improved maintainability and testability.
* Allows for parallel development by teams.
* Clear boundaries between different functional areas of the application.
  7.3. Rationale for Database Choices
* PostgreSQL: Robust, feature-rich relational database suitable for complex data models.
* Redis: High-performance key-value store ideal for caching, session management, and rate limiting.
* OpenSearch: Powerful search engine for providing fast and relevant search results (e.g., for courses).
* ClickHouse: Columnar database optimized for OLAP queries and analytics.
* InstantDB/Triplit: Real-time database capabilities.

## Appendix

* (Diagrams can be added here later if text-based representations are feasible)


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