Mr. Mentor / MAS Platform — Architecture & Engineering Documentation¶

This is the canonical developer documentation for the mr-mentor-backend service and the products it powers. The backend began as Mr. Mentor (1:1 mentorship + video meetings + a token economy) and has grown into a single Node/TypeScript codebase hosting a multi-product EdTech and recruitment suite: Mr. Mentor, Mr. Hire, the MAS LMS, Sales CRM, Finance/GST, an AI platform, a workflow engine, a vendor API, and a set of external integrations.

Every document is grounded in the real source under mr-mentor-backend/src and is heavily diagrammed with Mermaid (architecture flowcharts, entity-relationship diagrams, end-to-end user-journey sequence diagrams, and status state machines). All diagrams are validated to render on GitHub.

Tech stack: Node 20 · Express · TypeScript · TypeORM (PostgreSQL, auto-sync) · Redis + BullMQ · Socket.IO · AWS S3 · Razorpay · Nodemailer · Google OAuth/Calendar. Multi-tenant via the x-platform header.

How to navigate¶

If you want to understand…	Start here
The whole system at a glance	System Context & Container Architecture
A specific product/feature end-to-end	Feature docs below
The database / entities	Data Model
How requests, auth, jobs & realtime work	Architecture docs
How to build, deploy & operate it	DevOps docs
How to contribute code	Guidelines

Feature documentation¶

Each feature doc covers: overview & personas, key entities, an architecture flowchart, an ER diagram, the full API surface, per-journey sequence diagrams, background jobs, external integrations, status lifecycles, and gotchas.

Mr. Mentor — Mentorship Core¶

Identity, Authentication & Access Control — This document describes how the Mr. Mentor / MAS backend identifies a caller, proves who they are (signup + OTP, password login, Google OAuth, refresh-token rotation, an emergency master-password + TOTP path), and decides what they may…
Mentorship & Meetings (Mr. Mentor Core) — The original heart of the platform: students discover expert mentors, browse and request 30-minute
Token Economy & Token Governance — The token economy is the internal currency that gates premium, mentor-time-consuming actions on the
Mentor Earnings & Payouts — This domain governs how a mentor (an EXPERT-role user) earns money for completed 1:1 mentorship
Payments, Finance & GST Invoicing — This domain covers every flow where money moves through the MAS / Mr. Mentor

Mr. Hire — Recruitment Suite¶

Mr. Hire — Jobs, Applications & Candidate Quizzes — This document describes the recruitment / ATS core of Mr. Hire as implemented inside the
Mr. Hire — AI Resume Analysis & Screening — This document describes the AI-assisted resume analysis and candidate screening domain of the
Mr. Hire — Voice Interviews & AI Calling — This document is the canonical developer reference for the AI voice-calling surface of the MAS / Mr. Mentor backend. It covers three distinct but related calling systems that all live in this Node/Express backend: (1) candidate AI voice…
Mr. Hire — Talent Pool & Salary Benchmarking — This document describes two closely-related Mr. Hire (recruitment / ATS) sub-domains inside mr-mentor-backend:

MAS LMS — Learning & Students¶

MAS LMS — Courses, Batches, Modules & Enrollment — This document describes the education / learning domain of the Mr. Mentor backend: the public course catalog, the marketing-driven "MAS course" cards (cohorts, accelerators, capsules, deep-tech), the structured curriculum model (Course…
Assessments — Quizzes, Assignments & Question Bank — This document describes the assessment domain of the MAS / Mr. Mentor backend: course quizzes (manual + AI-generated), student quiz submissions and grading, assignments with a nightly due-date reminder worker, the shared Question Bank…
Student Portal — Profile, Activity & Dashboard — The student-facing surface of the MAS suite: the profile a learner fills in, the dashboard they land on, the activity feed and progress roll-up that track their journey, the profile-view analytics mentors generate, and the consolidated…
Student Engagement & Gamification — This document is the canonical developer reference for the Student Engagement & Gamification domain of the MAS / Mr. Mentor backend. It covers the four interlocking systems that drive the student dashboard's level ribbon and badges, the…
Applications & Onboarding (incl. IIMT) — This domain covers how a prospect becomes an enrolled MAS student: the generic application intake (the multi-step "apply to MAS" wizard backed by the applications table), the entity-subscriber side-effects that turn a fresh application…

External LMS / Exam Integrations¶

Integration — Mr. Learn (External LMS Sync) — This domain mirrors learner activity from Mr. Learn — the external Graphy LMS that MAS operates at mrlearn.in — into the Mr. Mentor backend's own PostgreSQL so that the admin dashboard, student dashboard and…
Integration — Mr. Test (External Exam Sync) — This domain integrates the MAS backend with Mr. Test — an external online-exam platform built on EzExam (a Django app reachable at https://myanalyticsschool.ezexam.in). Because EzExam exposes no public API and no JSON read-models for…
Integrations Hub — Graphy, EzExam, Judge0, Google Drive, Terminal Relay — This document is the canonical reference for the cluster of third-party and infrastructure integrations in mr-mentor-backend that do not belong to a single product domain: the Graphy / Mr Learn LMS connector, the EzExam / Mr Test…

Sales CRM¶

Sales CRM — Leads, Campaigns & Activity — The Sales CRM is the lead-management core of the MAS suite: it ingests prospects from many channels (CSV bulk uploads, third-party vendors, public website campaign forms, and manual entry), de-duplicates them into a single working pool…
Sales CRM — Assignment, Targets, Sales Head & Community Managers — This document is the canonical reference for the operational backbone of the MAS Sales CRM and post-sale student ops: how leads get assigned to telecallers and counsellors, the sales-head approval gate over bulk assignment, the…

Communications¶

Communications — Email, Templates & Notifications — This is the shared communications backbone of the MAS / Mr. Mentor backend: the
Communications — WhatsApp — WhatsApp is the platform's templated outbound + inbound messaging channel. It powers three distinct
Communications — Telephony (Exotel Click-to-Call & SMS) — Exotel powers the outbound voice and SMS channel for the Sales CRM. A salesperson (or sales head / admin)

AI, Workflow & Documents¶

AI Platform — LLM Gateway, Agents & Ask MAS — This document describes the backend's "AI platform" domain: the central LLM Gateway (a thin client over a self-hosted LiteLLM proxy) that mints per-user virtual API keys and meters spend, the Ask MAS student assistant that routes…
Workflow Automation Engine — The Workflow Automation Engine is a generic, node-based automation runtime that drives Sales CRM lead nurture end to end. An admin authors a visual graph (trigger → wait → send email / WhatsApp / AI call → branch) on a React-Flow…
Documents — E-Signing (Leegality) & PAP Agreements — This document describes how the MAS101 Pay-After-Placement (PAP) agreement is generated, signed

Platform Surfaces¶

Marketing — Banners, Events, League & Course Interest — This document covers the marketing surfaces of the Mr. Mentor / MAS backend: the sticky and pop-up banners that ride on top of the public website, the reusable banner-template asset library, the key/value event configuration store, the…
Vendor API Platform (Keys & Vendor Leads) — The Vendor API Platform is the backend's public-facing, B2B, server-to-server API surface. It lets
Admin, Ops, System Config & Bulk Tooling — This document covers the operational backbone of the Mr. Mentor backend: the admin dashboard surface, dynamic runtime configuration (SystemConfig), the Excel/JSON bulk-upload pipeline for onboarding users, ad-hoc data cleanup of expired…

Architecture and cross-cutting¶

System Context & Container Architecture (C4) — This is the entry-point architecture document for the MAS / Mr. Mentor backend. It explains, at a
Request Lifecycle & Middleware Pipeline — This document is the canonical reference for how an HTTP request travels through the
Multi-Platform / Multi-Tenant Architecture — How a single Express + TypeScript backend (mr-mentor-backend, port 8000) serves several brands and products at once — Mr. Mentor, My Analytics School (MAS), and the Mr. Hire HR portal — from one PostgreSQL database, one Redis/BullMQ…
Background Jobs & Queues (Redis + BullMQ) — All work in the Mr. Mentor backend that must not block an HTTP request — sending email, AI resume screening,
Real-time — Socket.IO, WebRTC Meetings & Terminal Relay — This document is the canonical reference for every real-time transport in the MAS / Mr. Mentor
External Integrations Catalog — A single, source-cited catalog of every third-party (and cross-service) integration the mr-mentor-backend API talks to: what it does, the service/controller that wraps it, the env vars it reads, whether traffic is outbound (the API…
Security & Authorization Architecture — This document is the canonical reference for how the Mr. Mentor / MAS backend authenticates callers, authorizes them against the role matrix, protects secrets, verifies inbound webhooks, and records security-relevant audit trails. It is…

Data model¶

Data Model — Entities & Relationships — This document is the canonical map of the TypeORM data model that backs the

DevOps and operations¶

Deployment Architecture — This document describes how the MAS / Mr. Mentor backend and its two companion frontends are
CI/CD Pipelines — This document is the canonical reference for the GitHub Actions CI/CD pipelines that build and deploy the three deployable MAS / Mr. Mentor web services: mr-mentor-backend (Express API), mr-mentor-frontend (Next.js admin/portal), and…
Environment & Configuration Reference — This document is the canonical reference for how the mr-mentor-backend service is configured: every environment variable it reads, the three-tier config-resolution model (process env -> runtime SystemConfig table -> build-time feature…
Infrastructure Topology — The runtime infrastructure that serves the MAS / Mr. Mentor backend in production and development:
Observability, Monitoring & Runbooks — This document is the operations playbook for the Mr. Mentor backend. It maps the

Engineering guidelines¶

Engineering Conventions & Code Style — This document is the canonical reference for how code is structured and written in the
Recipe — Adding a New Feature — This is the canonical, copy-pasteable recipe for adding a new vertical feature to the
API Design & Error Conventions — This guideline is the canonical reference for how HTTP APIs are shaped in the
Data & TypeORM Guidelines — This is the canonical engineering guideline for working with the persistence layer of the
Testing Strategy — This guideline documents how automated testing actually works in mr-mentor-backend today: the Bun test runner, the (parallel) ts-jest config, where tests live, the unit-vs-integration split, fixtures and test seeding, and — honestly —…
Git Workflow & Contribution Guide — This guide is the canonical reference for how code moves from a developer's laptop into production for the mr-mentor-backend repository (MAS-Mr-Mentor/mr-mentor-backend). It documents branch naming, commit-message conventions, the dated…

Document conventions¶

Diagrams use Mermaid and render natively on GitHub. Sequence diagrams trace a journey from the actor/frontend through routes → controllers → services → database/queue/external systems and back.
Source citations appear inline as code paths, e.g. src/services/AuthService.ts. Route paths are quoted exactly as mounted in src/routes/index.ts.
Claims that cannot be proven directly from code are marked (inferred).
Where a doc surfaced a real bug or security gap in the code, it is called out under Edge cases & gotchas rather than hidden.

Generated from source on branch claude/backend-architecture-docs.