Skip to main content

Technical Documentation: Learnille Server

1. Introduction​

1.1. Purpose This document provides detailed technical information for developers working on or integrating with the Learnille Server. It covers project setup, architecture, core technologies, module deep dives, API reference, development practices, and troubleshooting. 1.2. Getting Started 1.2.1. Prerequisites

  • Node.js (Version 22, as specified in package.json)
  • npm (comes with Node.js)
  • PostgreSQL (Version 14+ recommended by README.md in documentation folder, though not explicitly in server's package.json)
  • Redis (Version 7.0 recommended)
  • Access to other services as per src/config.ts for full functionality (Elasticsearch, ClickHouse, Novu, Paystack, S3, InstantDB, Shlink, Google).
  • Docker (optional, for running dependencies like Triplit server via docker-compose.yml). 1.2.2. Repository Setup
  • Clone the repository from the provided Git source.
  • Follow standard Git branching strategies if applicable. 1.2.3. Installation
  • Navigate to the server directory.
  • Run npm install to install dependencies listed in package.json. 1.2.4. Environment Configuration
  • Create environment-specific .env files within an env/ directory inside server/ (e.g., server/env/.env.local, server/env/.env.development).
  • Refer to server/src/config.ts (the validationSchema object) for the full list of required and optional environment variables. Key variables include database credentials, API keys for third-party services, JWT secrets, etc.
  • An example .env.example file should ideally be created and maintained at server/env/.env.example. 1.2.5. Running the Application
  • Local Development (with hot-reloading): npm run watch:local (sets NODE_ENV=local)
  • Development (without hot-reloading): npm run start:dev (sets NODE_ENV=development)
  • Staging: npm run start:staging (sets NODE_ENV=staging)
  • Production: npm run start:prod (sets NODE_ENV=prod) or using PM2: npm run start:pm2:prod
  • The application typically runs on port 3000 (or process.env.PORT). 1.2.6. Running Tests
  • Run all tests: npm test
  • Run tests with coverage: npm run test:cov
  • Run E2E tests: npm run test:e2e (requires separate Jest config test/jest-e2e.json)

2. Project Structure​

2.1. Overview of Key Directories (within server/)

  • src/: Contains all TypeScript source code.
  • env/: (Convention) Should contain environment-specific .env files.
  • dist/: Output directory for compiled JavaScript code (generated by npm run build).
  • test/: Contains end-to-end test configurations and possibly tests.
  • node_modules/: Contains installed npm packages. 2.2. Structure of src/
  • main.ts: Application entry point.
  • app.module.ts: Root NestJS module.
  • config.ts: Defines environment variable validation schema (validationSchema) and Config interface.
  • data-source.ts: Defines a TypeORM AppDataSource (likely for CLI use or defaults).
  • instrument.ts: Early instrumentation setup (e.g., Sentry).
  • Module-specific directories (e.g., users/, auth/, course/, payments/): Each contains controllers, services, modules, entities, DTOs for a specific feature.
  • common/: Likely contains shared utilities, decorators, pipes, guards, interceptors, filters.
  • assets/: Static assets, like MJML email templates, copied to dist/ during build.
  • database/: (Convention, if DatabaseModule is custom) Might contain database module setup.
  • winston/: Contains Winston logger service.
  • (Other directories for specific integrations like redis/, elastic/, bullmq/, novu/, etc.) 2.3. Key Configuration Files (at server/ root)
  • package.json: Project metadata, dependencies, scripts.
  • nest-cli.json: NestJS CLI configuration (source root, assets, plugins like Swagger).
  • tsconfig.json: TypeScript compiler options.
  • docker-compose.yml: Defines services for local development (currently only triplit-server).
  • .eslintrc.js, .prettierrc: ESLint and Prettier configurations for code linting and formatting.

3. Core Technologies & Concepts​

3.1. NestJS:

  • Modules (@Module): Organize code into reusable units. AppModule is the root.
  • Controllers (@Controller): Handle incoming HTTP requests and send responses.
  • Services (@Injectable): Encapsulate business logic, injected into controllers or other services.
  • Providers: Services, repositories, factories, helpers, etc., managed by NestJS DI.
  • Pipes (@PipeTransform): Transform or validate input data (e.g., ValidationPipe).
  • Guards (@CanActivate): Determine if a request can be handled by a route (e.g., JwtAuthGuard, CaslGuard).
  • Interceptors (@NestInterceptor): Bind extra logic before/after route handler execution (e.g., ResponseInterceptor).
  • Filters (@ExceptionFilter): Handle unhandled exceptions across the application (e.g., AllExceptionsFilter).
  • Decorators: Extensively used for metadata (e.g., @Get(), @Post(), @Body(), @CurrentUser()). 3.2. TypeORM:
  • Entities (@Entity): Define database table structures.
  • Repositories (@Repository or custom): Provide methods for database operations.
  • DataSource: Configuration object for database connections (seen in data-source.ts).
  • Migrations: Managed via scripts in package.json (e.g., npm run migrations:run).
  • Seeding: Scripts in package.json for populating initial data. 3.3. Configuration Management:
  • @nestjs/config with ConfigService.
  • .env files in env/ directory, selected by NODE_ENV.
  • Joi validation schema in src/config.ts.
  • Type-safe access using Config interface. 3.4. Logging:
  • nestjs-pino or Winston (conditional in main.ts).
  • AppRequestLoggerMiddleware for logging HTTP requests.
  • Sentry for error and performance monitoring. 3.5. Error Handling:
  • AllExceptionsFilter for global, standardized error responses.
  • Custom exceptions per module (e.g., PhotoNotFoundException).
  • Sentry integration in main.ts and for unhandled process exceptions. 3.6. Authentication & Authorization:
  • JWT (JSON Web Tokens) for stateless authentication.
  • Passport.js strategies (LocalStrategy, JwtStrategy, GoogleStrategy).
  • Guards (JwtAuthGuard, LocalAuthGuard, GoogleAuthGuard, LoginAuthGuard).
  • @CurrentUser() decorator to access authenticated user data.
  • CASL for fine-grained, ability-based authorization (seen in CourseController). 3.7. Background Jobs with BullMQ:
  • BullmqCustomModule for setup.
  • Used for tasks that can be processed asynchronously.
  • BullBoard for monitoring queues (setup in AppModule). 3.8. Caching with Redis:
  • RedisModule for integration.
  • Used by ThrottlerModule for rate limiting.
  • Potentially for application-level caching via CacheModule (if used). 3.9. API Documentation with Swagger:
  • @nestjs/swagger plugin enabled in nest-cli.json.
  • Setup in main.ts, available at /docs endpoint.
  • Controllers and DTOs use decorators like @ApiTags, @ApiOperation, @ApiBody, @ApiResponse, @ApiProperty for documentation. 3.10. Email Sending:
  • @nestjs-modules/mailer with Handlebars templates (src/assets/templates/*.mjml). 3.11. Notifications with Novu:
  • NovuModule integration.
  • WorkflowsService defines notification workflows.
  • Used for events like email verification, password reset.

4. Module Deep Dive​

4.1. Module: Users (src/users/) 4.1.1. Purpose and Responsibilities: Manages user profiles, core user data, roles, and profile picture handling. Provides services for user creation, retrieval, and updates. 4.1.2. Key Files:

  • users.module.ts: Imports TypeORM for User & Login entities, CryptoModule, GoogleModule, FilesModule, AuthModule. Exports UsersService.
  • users.controller.ts: Handles /user route. Endpoints for fetching (GET /) and updating (PUT /) the authenticated user's profile. Uses JwtAuthGuard and @CurrentUser().
  • users.service.ts: Contains logic for createUser (hashes password), getUserProfile (formats response, gets photo URL), updateUser (processes photo), findLoginWithUser, addUserTag, removeUserTag. Interacts with UsersRepository, CryptoService, FilesService.
  • entities/user.entity.ts: Defines the User schema with fields like id, name, email, password (hashed), roles, photo (OneToOne with File), verified status, timestamps, tags, etc.
  • dto/: Contains DTOs like UserCreate, UserUpdate, UserResponseDto. 4.1.3. API Endpoints (from UsersController):
  • GET /user: Get current authenticated user's profile. (Protected by JWT)
    • Response: UserResponseDto
  • PUT /user: Update current authenticated user's profile. (Protected by JWT)
    • Request Body: UserUpdate
    • Response: UserResponseDto 4.1.4. Data Models:
  • User entity (see user.entity.ts for details). 4.1.5. Core Workflows & Business Logic:
  • Profile Fetching: Retrieve user, get public URL for photo if exists.
  • Profile Update: Validate input, process photo (check existence, MIME type, usage by others), update user record.
  • User Creation (in service): Hash password, save user. 4.1.6. Events Emitted/Handled: (Not explicitly seen in these files, but AuthService emits USER_REGISTRATION_SUCCESSFUL which involves UsersService).

4.2. Module: Auth (src/auth/) 4.2.1. Purpose and Responsibilities: Handles all aspects of user authentication, including registration, login (local, Google), password management (change, forgot, reset), email verification, and JWT generation/validation. 4.2.2. Key Files:

  • auth.module.ts: Imports PassportModule, UsersModule, GoogleModule, CryptoModule, TypeORM for Login, User, ForgotPassword, VerifyEmail entities. Provides strategies, guards, AuthService, LoginsService. Exports AuthService.
  • auth.controller.ts: Handles /auth routes. Endpoints for check-email, register, login, change-password, code (request verification/reset code), forgot-password, reset-password, verify-email.
  • auth.service.ts: Core logic for all auth operations. Interacts with UsersService, CryptoService, notification services (WorkflowsService), and repositories for ForgotPassword, VerifyEmail. Generates codes, signs JWTs, validates credentials.
  • entities/: Contains Login, ForgotPassword, VerifyEmail entities.
  • guards/: Contains JwtAuthGuard, LocalAuthGuard, GoogleAuthGuard, LoginAuthGuard.
  • strategies/: Contains LocalStrategy, JwtStrategy, GoogleStrategy.
  • dto/: Contains DTOs like UserRegisterDto, LoginDto, ChangePasswordDto, ResetPasswordDto, VerifyEmailDto. 4.2.3. API Endpoints (from AuthController):
  • GET /auth/check-email?email=<email>: Check if email is available.
  • POST /auth/register: Register a new user. Body: UserRegisterDto. Response: RegisterResponse (includes JWT).
  • POST /auth/login: Login with email/password. Body: LoginDto. Response: LoginResponse (includes JWT). (Protected by LoginAuthGuard)
  • POST /auth/change-password: Change password for authenticated user. Body: ChangePasswordDto. (Protected by JwtAuthGuard)
  • POST /auth/code: Request a verification/reset code. Body: RequestCodeDto.
  • GET /auth/forgot-password?email=<email>: Initiate forgot password flow.
  • POST /auth/reset-password: Reset password using code. Body: ResetPasswordDto.
  • POST /auth/verify-email: Verify email using code. Body: VerifyEmailDto. 4.2.4. Data Models:
  • Login entity: Tracks login attempts/sessions.
  • ForgotPassword entity: Stores tokens for password reset.
  • VerifyEmail entity: Stores tokens for email verification. 4.2.5. Core Workflows & Business Logic:
  • Registration: Validate email, create user (via UsersService), create role-specific profile, trigger Novu verification email, return JWT.
  • Login: Validate credentials (via LocalStrategy), generate JWT.
  • Password Reset: Generate code, store it, send via Novu, verify code, update password, trigger Novu notification.
  • Email Verification: Generate code, store it, send via Novu, verify code, update user's verified status. 4.2.6. Events Emitted/Handled: Emits AppEvents.USER_REGISTRATION_SUCCESSFUL after successful registration. UserRegisteredListener likely handles this.

4.3. Module: Course (src/course/) 4.3.1. Purpose and Responsibilities: Manages all aspects of e-learning courses, including creation, content organization (sections, subsections, items), instructor associations, pricing, publishing, and retrieval. 4.3.2. Key Files:

  • course.module.ts: Imports TypeORM for numerous course-related entities (Course, CourseSection, Instructor, Category, etc.). Integrates StorageModule, ElasticModule, EnrollmentModule. Provides CourseService, CourseSectionService, etc. Exports CourseService.
  • course.controller.ts: Handles /course routes. Extensive endpoints for CRUD on courses, sections, subsections, items. Also handles course levels, properties (requirements, audience), summaries, and statistics. Uses JwtAuthGuard, CaslGuard, @AllowPublicView. Implements pagination.
  • course.service.ts: Core logic for course creation (validation, slug generation, file handling, manager assignment), retrieval (single, paginated list with processed output including file URLs), updates (ownership checks), deletion. Interacts with many repositories and services (FilesService, SlugService, CourseElasticService, TextWithIconService).
  • entities/course.entity.ts: Defines the main Course schema with fields for title, content structure, pricing, instructor, category, files, status, etc.
  • entities/sections.entity.ts, subsections.entity.ts, course_item.entity.ts, level.entity.ts, requirement.entity.ts: Define related data models.
  • dto/: Contains DTOs like CreateCourseDto, UpdateCourseDto, CourseResponseDto, DTOs for sections, subsections, items. 4.3.3. API Endpoints (Selected from CourseController):
  • POST /course: Create a new course. Body: CreateCourseDto. (Protected by JWT, CASL)
  • GET /course: Get all courses (paginated). (Protected by JWT, filters by instructor)
  • GET /course/slug/:slug: Get course by slug. (Publicly viewable with view options)
  • GET /course/:id: Get course by ID. (Publicly viewable with view options)
  • PUT /course/:id: Update a course. Body: UpdateCourseDto. (Protected by JWT, CASL)
  • DELETE /course/:id: Delete a course. (Protected by JWT, CASL)
  • CRUD endpoints for /course/section, /course/subsection, /course/item.
  • Endpoints for /course/levels, /course/summaries/:id, /course/:id/statistics.
  • Endpoints for managing course properties (requirements, etc.) like /course/:courseId/:type/replace. 4.3.4. Data Models:
  • Course entity (see course.entity.ts for details).
  • CourseSection, CourseSubSection, CourseItem, Level, Requirement, Inclusion, Audience entities. 4.3.5. Core Workflows & Business Logic:
  • Course Creation: Extensive validation, file handling for thumbnail/video, slug generation, linking to instructor/category, creating manager associations, emitting COURSE_CREATED event.
  • Course Retrieval: Fetching course with relations, processing file URLs, serializing output based on view groups. Paginated listing with filtering.
  • Course Update: Ownership validation, updating fields and relations.
  • Content Management: CRUD operations for hierarchical course content (sections, subsections, items). 4.3.6. Events Emitted/Handled: Emits AppEvents.COURSE_CREATED.

4.4. Module: Consultation (src/consultation/) 4.4.1. Purpose and Responsibilities: Manages the creation, scheduling, booking, delivery, and review of consultation services. Supports one-off and recurring consultation types, consultant availability management, and payment integration. 4.4.2. Key Files:

  • consultation.module.ts: Imports TypeORM for Consultation, Booking, ConsultationTimeSlot, ConsultationSession, OneOffConsultationMeta, RecurringConsultation, etc. Integrates ElasticModule, FilesModule, SharedModule, ReviewsModule, CategoryModule. Provides ConsultationService, SessionsService, TimeslotService.
  • consultation.controller.ts: Handles /consultation routes. Endpoints for CRUD on consultation offerings, managing availability (timeslots), booking, handling one-off/recurring specifics, and managing descriptive properties (benefits, questions). Uses JwtAuthGuard, @AllowPublicView.
  • consultation.service.ts: Core logic for creating/updating consultation offerings (validating consultant, category, files, sale dates, type-specific meta), finding consultations (single, paginated with processed output including file URLs), managing bookings, and interacting with timeslot/session logic. Integrates with ProductAccessService, FilesService, SlugService, ElasticService, NotificationService.
  • sessions.service.ts: Logic for managing consultation sessions and checking timeslot availability.
  • timeslot.service.ts: Logic for consultants to define and manage their availability.
  • entities/consultation.entity.ts: Main schema for consultation offerings (title, description, consultant, type, pricing, scheduling rules, links to properties, sessions).
  • entities/booking.entity.ts: Schema for user bookings.
  • entities/timeslot.entity.ts: Schema for consultant availability slots.
  • entities/sessions.entity.ts: Schema for individual consultation sessions.
  • entities/oneoff.entity.ts, recurring-consultation.entity.ts: Schemas for type-specific metadata.
  • dto/: Contains DTOs like CreateConsultationDto, UpdateConsultationDto, CreateBookingDto, ConsultationAvailabilityDto, OneoffInfoDto, RecurringInfoDto, ConsultationResponseDto. 4.4.3. API Endpoints (Key Examples from ConsultationController):
  • POST /consultation: Create a new consultation offering. (Protected)
  • GET /consultation: Get all consultations (paginated). (Protected)
  • GET /consultation/:id or GET /consultation/slug/:slug: Get specific consultation. (Publicly viewable)
  • PUT /consultation/:id: Update consultation. (Protected)
  • POST /consultation/booking: Create a new booking. (Protected)
  • PUT /consultation/:consultationId/availability: Update consultant's availability for a consultation. (Protected)
  • GET /consultation/:consultationId/availability: Get availability for a consultation. (Protected)
  • POST /consultation/:consultationId/oneoff or /recurring: Add type-specific details. (Protected)
  • CRUD endpoints for properties like benefits, questions under /consultation/:consultationId/:type. (Protected) 4.4.4. Data Models:
  • Consultation entity (details key fields like consultant, type, pricing, scheduling rules, links to sessions, bookings, properties).
  • Booking entity (links user to consultation/session, status).
  • ConsultationTimeSlot entity (defines consultant's available slots).
  • ConsultationSession entity (represents an actual scheduled session). 4.4.5. Core Workflows & Business Logic:
  • Consultation Creation: Validation of consultant, category, files; generation of slug; setting default availability; emitting CONSULTATION_CREATED event.
  • Consultation Retrieval: Fetching with relations, processing file URLs, serializing based on view groups, fetching type-specific metadata.
  • Availability Management: Consultants define timeslots; service checks for conflicts.
  • Booking: User selects consultation & timeslot; system validates availability, creates booking, potentially links to a session, initiates payment. 4.4.6. Events Emitted/Handled: AppEvents.CONSULTATION_CREATED, AppEvents.CONSULTATION_UPDATED.

4.5. Module: Payments (src/payments/) 4.5.1. Purpose and Responsibilities: Handles all financial transactions, including processing payments for orders via gateways like Paystack, managing payment records, and providing user wallet functionalities (balance, withdrawals). 4.5.2. Key Files:

  • payments.module.ts: Imports TypeORM for Payment, CoursePayment, ConsultationPayment, Withdrawal, Order, Coupon entities. Integrates PaystackModule, UsersModule, EnrollmentModule, CourseModule, ConsultationModule, CouponModule, CartModule. Provides PaymentsService, WalletService.
  • payments.controller.ts: Handles /payment routes. Endpoints for creating payments (POST /), finding user's payments (GET /), finding a specific payment (GET /:id), regenerating payment links (POST /regenerate-link), and a Paystack webhook (POST /paystack-webhook).
  • wallet.controller.ts: Handles /wallet routes. Endpoints for provider payment overview (GET /overview/:providerId) and revenue charts (GET /revenue-chart/:providerId).
  • payments.service.ts: Core logic for initiating payments (via _initiatePaymentForOrder which interacts with PaystackService), creating Payment records, retrieving payment history.
  • wallet.service.ts: Logic for calculating provider earnings, balances, processing withdrawal requests (creation part), and generating revenue reports.
  • entities/payment.entity.ts: Main schema for payment transactions (amount, fees, currency, status, gateway info, links to Order, Payer (User), Student (beneficiary)).
  • entities/withdrawal.entity.ts: Schema for user withdrawal requests, including amount and status (PENDING, COMPLETED, etc.).
  • dto/: Contains DTOs like CreatePaymentDto, RegeneratePaymentLinkDto, PaymentResponseDto, GetOverviewResponseDto. 4.5.3. API Endpoints (Key Examples):
  • From PaymentsController:
    • POST /payment: Initiate a payment for an order. Body: CreatePaymentDto. (Protected)
    • GET /payment: Get authenticated user's payment history (paginated). (Protected)
    • GET /payment/:id: Get details of a specific payment. (Protected)
    • POST /payment/regenerate-link: Regenerate payment link for an order. Body: RegeneratePaymentLinkDto. (Protected)
    • POST /payment/paystack-webhook: Handles Paystack webhook events (Unauthenticated, internal).
  • From WalletController:
    • GET /wallet/overview/:providerId: Get payment overview for a provider. (Protected)
    • GET /wallet/revenue-chart/:providerId?period=<period>: Get revenue chart data for a provider. (Protected, admin can specify providerId) 4.5.4. Data Models:
  • Payment entity (details key fields: amount, fees, currency, status, gateway, ref, links to Order, Payer, Student).
  • Withdrawal entity (links to User, amount, status). 4.5.5. Core Workflows & Business Logic:
  • Payment Initiation: Triggered by OrderService (likely). PaymentsService validates order, prepares data, calls gateway service (PaystackService) to get auth URL. A Payment record is created in PENDING state.
  • Payment Confirmation: Paystack webhook hits controller, PaystackService processes it, PaymentsService (or OrderService via events) updates Payment and Order status. Post-payment actions (enrollment, notifications) are triggered.
  • Wallet Operations:
    • Balance Calculation: WalletService calculates a provider's balance by subtracting total completed withdrawals from their total earnings (final amount from payments where they are the provider).
    • Revenue Reporting: Provides data for revenue charts over specified periods for providers.
    • Withdrawal Requests: WalletService allows for the creation of Withdrawal records in a PENDING state. (Actual processing/payout mechanism is not detailed in this service).
    • Overview: Provides a consolidated view of a provider's total sales, withdrawals, and current balance. 4.5.6. Events Emitted/Handled: (Events are likely emitted upon successful payment confirmation to trigger other module actions like enrollment, rather than during initiation).

4.6. Module: Instructors (src/instructors/) 4.6.1. Purpose and Responsibilities: Manages instructor-specific profiles, their professional details (experience, achievements, expertise), resume, and their association with courses and the base user system. 4.6.2. Key Files:

  • instructors.module.ts: Imports TypeORM for Instructor, User, CourseManager. Integrates CourseModule, SharedModule, FilesModule, EnrollmentModule. Provides InstructorsService.
  • instructors.controller.ts: Handles /instructor routes. Endpoints for creating (POST /), fetching (GET /:id?, with public/private views), updating (PUT /:id), and deleting (DELETE /:userId, admin-only) instructor profiles. Also includes endpoints for managing instructor availability via a shared ProviderService.
  • instructors.service.ts: Core logic for CRUD operations on instructor profiles. Handles linking to User, managing achievements and experiences (via ProviderService), resume uploads (via FilesService), and cascading deletion of courses upon instructor removal. Performs access checks for updates/deletions. Provides an overview endpoint integrating with EnrollmentService.
  • entities/instructor.entity.ts: Defines the Instructor schema with fields for overview, description, expertise, languages, position, institution, social links, and relations to User (OneToOne), Course (OneToMany), File (for resume), Experience, and Achievement.
  • entities/manager.entity.ts: Defines a course manager, linking an instructor to a course in a managerial capacity.
  • dto/: Contains DTOs like CreateInstructorDto, UpdateInstructorDto, InstructorResponseDto. 4.6.3. API Endpoints (Key Examples from InstructorsController):
  • POST /instructor: Create an instructor profile for the authenticated user. Body: CreateInstructorDto. (Protected)
  • GET /instructor/:id? (or by email/slug): Get instructor profile. (Publicly viewable with view options)
  • PUT /instructor/:id: Update instructor profile (user ID as :id). Body: UpdateInstructorDto. (Protected, owner/admin)
  • DELETE /instructor/:userId: Delete instructor profile. (Admin-only)
  • GET /instructor/overview/:id?: Get instructor overview/statistics. (Protected)
  • GET /instructor/availability, PUT /instructor/availability: Manage instructor availability (via ProviderService). (Protected) 4.6.4. Data Models:
  • Instructor entity (details key fields: link to User, overview, expertise, experiences, achievements, resume, courses).
  • CourseManager entity (links Instructor to Course as a manager). 4.6.5. Core Workflows & Business Logic:
  • Profile Creation: Link to existing User, add Instructor role to User, save professional details (experiences, achievements via ProviderService), handle resume upload. Emit INSTRUCTOR_CREATED event.
  • Profile Retrieval: Fetch instructor and associated user data, format resume URL, serialize based on view groups.
  • Profile Update: Access control, update fields, handle resume/experience/achievement updates. Emit INSTRUCTOR_UPDATED event.
  • Profile Deletion (Admin): Cascade delete associated courses, then delete instructor profile. Emit INSTRUCTOR_REMOVED event. 4.6.6. Events Emitted/Handled: AppEvents.INSTRUCTOR_CREATED, AppEvents.INSTRUCTOR_UPDATED, AppEvents.INSTRUCTOR_REMOVED.

4.7. Module: Consultant (src/consultant/) 4.7.1. Purpose and Responsibilities: Manages consultant-specific profiles, their professional details (experience, achievements, expertise), resume, availability, and their association with consultation services and the base user system. 4.7.2. Key Files:

  • consultant.module.ts: Imports TypeORM for Consultant, User, Achievement, Experience, File, Availability, TimeSlot, and various consultation-related entities. Integrates SharedModule, ReviewsModule, FilesModule. Provides ConsultantService and re-provides SessionsService (from consultation module).
  • consultant.controller.ts: Handles /consultant routes. Endpoints for creating (POST /), fetching (GET /:id?, with public/private views), updating (PUT /:userId), and deleting (DELETE /:userId) consultant profiles. Also includes endpoints for managing consultant availability (via ProviderService) and viewing calendar events/upcoming sessions (via SessionsService).
  • consultant.service.ts: Core logic for CRUD operations on consultant profiles. Handles linking to User, managing achievements and experiences (via ProviderService), resume uploads (via FilesService). Performs access checks for updates/deletions. Provides methods for getCalendarEvents and a stubbed getOverview.
  • entities/consultant.entity.ts: Defines the Consultant schema with fields for about, description, expertise, languages, professional background, social links, and relations to User (OneToOne), Consultation (OneToMany), File (for resume), Experience, and Achievement.
  • entities/consultant-meta.entity.ts: (Purpose to be clarified if distinct from Consultant entity fields).
  • entities/timeslot.entity.ts: (If specific to consultant, or if it's the shared one for availability).
  • dto/: Contains DTOs like CreateConsultantDto, UpdateConsultantDto, ConsultantResponseDto. 4.7.3. API Endpoints (Key Examples from ConsultantController):
  • POST /consultant: Create a consultant profile for the authenticated user. Body: CreateConsultantDto. (Protected)
  • GET /consultant/:id? (or by email/slug): Get consultant profile. (Publicly viewable with view options)
  • PUT /consultant/:userId: Update consultant profile. Body: UpdateConsultantDto. (Protected, owner/admin)
  • DELETE /consultant/:userId: Delete consultant profile. (Protected, owner/admin - service enforces)
  • GET /consultant/overview: Get consultant overview. (Protected)
  • GET /consultant/availability, PUT /consultant/availability: Manage consultant availability (via ProviderService). (Protected)
  • GET /consultant/calendar: Get consultant's calendar events. (Protected)
  • GET /consultant/sessions/upcoming: Get consultant's upcoming sessions. (Protected) 4.7.4. Data Models:
  • Consultant entity (details key fields: link to User, professional background, expertise, resume, consultations offered). 4.7.5. Core Workflows & Business Logic:
  • Profile Creation: Link to existing User, add Consultant role to User, save professional details, handle resume. Emit CONSULTANT_CREATED event.
  • Profile Retrieval: Fetch consultant and associated user data, format resume URL, serialize based on view groups, fetch experiences/achievements via ProviderService.
  • Profile Update: Access control, update fields, handle resume/experience/achievement updates. Emit CONSULTANT_UPDATED event.
  • Profile Deletion: Access control, delete associated provider-specific data (achievements, experiences, availability), then delete consultant profile. Emit CONSULTANT_REMOVED event. 4.7.6. Events Emitted/Handled: AppEvents.CONSULTANT_CREATED, AppEvents.CONSULTANT_UPDATED, AppEvents.CONSULTANT_REMOVED.

4.8. Module: Cart (src/cart/) 4.8.1. Purpose and Responsibilities (High-Level): Manages user shopping carts, allowing items (courses, consultations) to be added, viewed, and removed before checkout. 4.8.2. Key Interactions: UsersModule (user association), CourseModule/ConsultationModule (product details), CouponModule (potential pre-order discount application), OrderModule (for converting cart to order). 4.8.3. Core Entities: Cart, CartItem.

4.9. Module: Order (src/order/) 4.9.1. Purpose and Responsibilities (High-Level): Handles the creation and management of orders from cart items or direct product selections. Calculates totals, applies coupons, and interfaces with PaymentModule to initiate payment and EnrollmentModule for fulfillment. 4.9.2. Key Interactions: CartModule (source of items), CouponModule (discounts), PaymentModule (payment processing), EnrollmentModule (fulfillment), UsersModule (user association), CourseModule/ConsultationModule (item details). 4.9.3. Core Entities: Order, OrderItem.

4.10. Module: Reviews (src/reviews/) 4.10.1. Purpose and Responsibilities (High-Level): Manages user-submitted reviews and ratings for products like courses and consultations. Handles review creation, retrieval, and aggregation of rating statistics. 4.10.2. Key Interactions: UsersModule (reviewer identity), CourseModule/ConsultationModule (reviewed entity context), EnrollmentModule (review eligibility). 4.10.3. Core Entities: Review.

4.11. Module: Marketplace (src/marketplace/) 4.11.1. Purpose and Responsibilities (High-Level): Provides public-facing API endpoints for searching, filtering, and discovering products (courses, consultations). Integrates recommendation logic. 4.11.2. Key Interactions: ElasticModule (primary data source for search), RecommendationModule, CourseModule/ConsultationModule (for product data structure). 4.11.3. Core Entities: (Primarily acts on data indexed in Elasticsearch, but references Course, Consultation entities).

4.12. Module: Students (src/students/) 4.12.1. Purpose and Responsibilities (High-Level): Manages student-specific profiles (linked to User accounts) and provides access to their enrollment data. 4.12.2. Key Interactions: UsersModule (base user data), EnrollmentModule (fetches student's enrollments). 4.12.3. Core Entities: Student.

4.13. Module: Impression (src/impression/) 4.13.1. Purpose and Responsibilities (High-Level): Tracks user impressions (views/interactions) for content like courses and consultations. Data is likely used for analytics. 4.13.2. Key Interactions: CourseModule/ConsultationModule (to identify entities being viewed). May log to an external system or update counters. 4.13.3. Core Entities: (May not have its own persistent entity in primary DB if data is offloaded).

4.14. Module: Enrollment (src/enrollment/) 4.14.1. Purpose and Responsibilities (High-Level): Manages user enrollments in products (courses, consultations), often triggered by successful payments. Tracks enrollment status and potentially granular progress (e.g., section completion). 4.14.2. Key Interactions: UsersModule/StudentsModule (enrolled user), CourseModule/ConsultationModule (enrolled product), PaymentModule (trigger for enrollment), OrderModule. Contains EnrollmentListener for event-driven actions. 4.14.3. Core Entities: Enrollment, SectionEnrollment.

4.15. Module: Comms (src/comms/) 4.15.1. Purpose and Responsibilities (High-Level): Integrates with third-party communication platforms (e.g., Stream, CometChat) for features like chat/calls. Manages user authentication tokens for these services and handles user provisioning on these platforms, often via event listeners (e.g., NewUserListener). 4.15.2. Key Interactions: UsersModule (user context), ConfigModule (API keys), HttpModule (external API calls), StreamModule. 4.15.3. Core Entities: UserAuthTokens.

4.16. Module: Category (src/category/) 4.16.1. Purpose and Responsibilities (High-Level): Manages a hierarchical system of categories and subcategories used to classify products like courses and consultations. Provides admin CRUD operations and public retrieval. 4.16.2. Key Interactions: CourseModule/ConsultationModule (products are assigned to categories), FilesModule (for category images). 4.16.3. Core Entities: Category.

5. API Reference​

5.1. General Principles: RESTful, JSON-based. Standardized response format is implemented via ResponseInterceptor. 5.2. Authentication: Bearer Token (JWT) required for most endpoints. Sent in Authorization header. 5.3. Rate Limiting: Applied globally via ThrottlerModule and ThrottlerGuard, using Redis for storage. Limits configured via environment variables (THROTTLE_TTL, THROTTLE_LIMIT). 5.4. Common Status Codes and Error Formats: Standard HTTP status codes. Errors handled by AllExceptionsFilter, providing a consistent JSON error response structure. 5.5. API Documentation: Available at /docs (Swagger UI).

6. Database Schema & Migrations​

6.1. Overview of Key Tables/Entities: users, logins, forgot_passwords, verify_emails, courses, course_sections, course_subsections, course_items, instructors, categories, files, etc. (Detailed in entity files). 6.2. Running Migrations: npm run migrations:run -- -d ./src/migrations-data-source.ts (or similar, path might vary slightly based on package.json). 6.3. Creating New Migrations: npm run migrations:generate -- -d ./src/migrations-data-source.ts ./src/migrations/$npm_config_name 6.4. Seeding Data: npm run seed:local (or other environment-specific seed scripts).

7. Development Practices​

7.1. Coding Standards: Enforced by ESLint and Prettier (configs: .eslintrc.js, .prettierrc). 7.2. Testing Strategies: Jest framework. package.json includes scripts for unit tests (npm test), coverage (npm run test:cov), and E2E tests (npm run test:e2e). 7.3. Debugging Techniques: Use Node.js debugger, NestJS verbose logging (for local/dev), Sentry for error tracking in deployed environments. Source maps are generated.

8. Deployment​

8.1. Build Process: npm run build (uses nest build which invokes TypeScript compiler). 8.2. Required Environment Variables: See src/config.ts validationSchema for a comprehensive list. Key categories include server ports, database credentials, JWT secrets, API keys for Paystack, Novu, S3, Google, ClickHouse, InstantDB, Shlink, Redis, SMTP. 8.3. Production Startup: npm run start:prod or npm run start:pm2:prod (uses PM2 for process management).

9. Troubleshooting Guide​

9.1. Common Startup Issues:

  • Port conflicts (use kill-port as seen in main.ts, or check lsof -i :<port>).
  • Database connection errors (check .env credentials, DB server status, network).
  • Missing environment variables (application will likely fail validation at startup).
  • Redis connection errors. 9.2. Interpreting Logs: Check console output for NestJS logs, Winston/Pino logs (for staging/prod), and Sentry for detailed error reports with stack traces. 9.3. API Error Debugging: Use Swagger UI (/docs) or tools like Postman/Insomnia to test endpoints. Check API response structure and error messages.

10. Chat Flow Architecture​

This section provides a comprehensive overview of the chat flow architecture, which is built around InstantDB and a robust event-driven system. This design ensures that chat rooms for categories, courses, and consultations are created, updated, and synchronized in a scalable and decoupled manner.

10.1. High-Level Overview​

The architecture leverages an event-driven approach to manage the lifecycle of chat rooms. When a significant action occurs in the system—such as creating a course, updating a category, or enrolling in a consultation—an event is emitted. A dedicated listener, the InstantListener, subscribes to these events and executes the corresponding logic to create or update rooms and participants in InstantDB.

This approach decouples the core business logic of each module (e.g., CourseService, CategoryService) from the chat functionality, leading to a more maintainable and scalable system.

10.2. InstantDB Schema (server/src/instantdb/schema/instant.schema.ts)​

The InstantDB schema is central to the chat functionality. It defines the entities and their relationships, enabling real-time communication and data synchronization.

10.2.1. Key Entities​

  • users: Stores user profile information, such as name, email, and photo URL.
  • rooms: Represents a chat room. It includes properties like name, type (e.g., GROUP, PRIVATE), entityType (e.g., COURSE, CONSULTATION), and imageUrl.
  • participants: Links a user to a room, defining their role (e.g., INSTRUCTOR, STUDENT).
  • messages: Represents a single message within a room.

10.2.2. participantUser Relationship​

A key enhancement to the schema is the participantUser link. This creates a direct relationship between a participant and a user, allowing the frontend to efficiently retrieve detailed user information for each participant in a room without additional queries.

// server/src/instantdb/schema/instant.schema.ts
links: {
    // ...
    participantUser: {
      forward: { on: "participants", has: "one", label: "user" },
      reverse: { on: "users", has: "many", label: "participations" },
    },
    // ...
}

10.3. Event-Driven Synchronization (server/src/instantdb/listeners/instant.listener.ts)​

The InstantListener is the core of the synchronization process. It subscribes to application-wide events and triggers the appropriate actions in the InstantdbService.

10.3.1. Room Creation and Updates​

  • Categories:
    • onCategoryCreated: When a parent category is created, a COMMUNITY room is created in InstantDB with the category's name and thumbnail imageUrl.
    • onCategoryUpdated: When a category is updated, the corresponding room's name, status, and imageUrl are updated.
  • Courses:
    • onCourseCreated: When a course is created, a GROUP room is created with the course's title and thumbnail imageUrl. The instructor is automatically added as a participant.
    • onCourseUpdated: When a course is updated, the corresponding room's name and imageUrl are updated.
  • Consultations:
    • onEnrollmentCreated: When a student enrolls in a consultation, a PRIVATE room is created. The room name is dynamically generated from the consultant's and student's first names, and the consultation's thumbnail is used as the imageUrl. Both the consultant and the student are added as participants.

10.4. Sequence Diagrams​

10.4.1. Consultation Enrollment and Room Creation​

This diagram illustrates the flow when a user enrolls in a consultation, resulting in the creation of a private chat room.

sequenceDiagram
    participant User
    participant EnrollmentService
    participant EventEmitter
    participant InstantListener
    participant InstantdbService

    User->>EnrollmentService: enrollInConsultation(data)
    EnrollmentService->>EnrollmentService: save(enrollment)
    EnrollmentService->>EventEmitter: emit('enrollment.consultation.successful', enrollment)
    
    EventEmitter->>InstantListener: handleConsultationEnrollment(enrollment)
    InstantListener->>InstantdbService: createRoom(roomData)
    InstantdbService-->>InstantListener: room
    InstantListener->>InstantdbService: createRoomParticipant(consultant)
    InstantListener->>InstantdbService: createRoomParticipant(student)

Appendix​

  • List of Key Environment Variables and their purpose (can be derived from src/config.ts).
  • Glossary