# selleo/mentingo architecture

> Architecture diagram of the GitHub repository selleo/mentingo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/selleo/mentingo
- Repository: https://github.com/selleo/mentingo

## Overview

1. This is a monorepo for an LMS platform with three runnable apps: `apps/api` (NestJS backend), `apps/web` (Remix frontend), and `apps/reverse-proxy` (Caddy for local HTTPS/domain routing). The rest of the repo is shared libraries, generated artifacts, tests, and deployment/ops assets.

2. The backend is a modular NestJS monolith, not a microservice swarm. Each major domain lives in its own module under `apps/api/src` with a familiar controller/service/repository split. The largest domains are courses, lessons, users, auth, live training, learning paths, SCORM, file/video handling, announcements, analytics/statistics, AI, chat, settings, groups, and tenant administration.

3. Persistence is Postgres-backed and migration-driven. Database schema and migrations live in `apps/api/src/storage`, with Drizzle configs and a long migration history. The data model is strongly tenant-aware: tenant resolution, tenant state, and tenant row-level security are central architectural concerns rather than an afterthought.

4. Multi-tenancy is enforced in the backend data layer. `storage/db` contains tenant resolution, tenant DB runners, ALS-based request context, and an RLS interceptor. Many tables are tenant-scoped, and migrations explicitly enable RLS for core tables like permissions, outbox events, integration keys, learning paths, SCORM, and search documents.

5. The main backend write path is synchronous request handling plus asynchronous side effects. Controllers accept HTTP requests, services apply business rules, repositories persist state, and domain events/outbox records fan out to background work. This is visible in the `events` tree, `outbox` module, queues, workers, cron jobs, and per-domain handlers.

6. Background processing is a first-class subsystem. There are dedicated workers and queue services for activity logs, courses, master courses, learning paths, ingestion, audio transcription, Luma sync, SCORM import, and other long-running tasks. This keeps expensive jobs, external calls, and scheduled jobs off the request thread.

7. External integrations are woven into the backend boundaries. Auth supports local login plus Google, Microsoft, and Slack OAuth. Email is abstracted via adapters for SES, SMTP, and local/dev delivery. File and media flows integrate with S3, Bunny, Tus uploads, and video processing. Live training integrates with LiveKit, payments with Stripe, and observability with Sentry and Langfuse.

8. AI and knowledge ingestion are a distinct subsystem, not a feature flag. The `ai` module handles chat, threads, prompts, RAG, token accounting, summaries, and evaluation logic. The `ingestion` module chunks documents, generates embeddings, and populates vector/search-backed storage. Prompt definitions live in `packages/prompts`, and evaluation datasets/docs are checked in under `docs/evaluation-datasets`.

9. The frontend is a Remix application organized by product modules rather than technical layers. Routes and pages are composed from `apps/web/app/modules`, with feature-specific components, hooks, stores, schemas, and utilities living alongside the page entry points. It behaves like a client-heavy SPA, but Remix still provides routing, server entry, and SSR/hydration boundaries.

10. The web app talks to the API primarily through a generated TypeScript client and domain-specific hooks. `app/api/generated-api.ts` and the many query/mutation hooks show a deliberate API boundary: frontend features consume typed operations instead of calling REST endpoints ad hoc. WebSocket hooks are used where real-time updates matter, especially for live training, course chat, video upload state, and course-generation sync.

11. Authentication, authorization, and tenant/role access are enforced across both layers. The backend has JWT, refresh-token, feature, permission, tenant, staging, and support-mode guards; the frontend mirrors this with route/access guards and role-aware navigation. Support mode and super-admin tenant management are explicit product concepts with their own modules and UI surfaces.

12. Content and learning flows form the core business graph: courses contain chapters and lessons, lessons can be content, quiz, embed, SCORM, live training, or AI mentor experiences, and learning paths can aggregate courses and certificates. Surrounding modules like announcements, news, articles, Q&A, categories, groups, calendar, statistics, and learning time all feed the same tenant-scoped learning experience.

13. There are several specialized delivery pipelines. SCORM has both export/runtime packages (`packages/scorm-export-generator`, `packages/scorm-export-runtime`) and backend import/runtime support. Email templates are isolated in `packages/email-templates`. Shared constants, types, and utilities live in `packages/shared`, while `packages/ui` and `packages/typescript-config` provide cross-app design-system and config reuse.

14. Quality and deployment are built into the repo structure. Tests span Jest/Vitest unit tests, NestJS E2E tests, Playwright web E2E tests, and k6 performance scenarios. GitHub Actions, Dockerfiles, Compose files, and the Caddy reverse proxy indicate the app is intended to run as a containerized, multi-service system with separate frontend, API, database, and ancillary services like Mailhog.

Main entry points: [`apps/api`](https://github.com/selleo/mentingo/tree/main/apps/api) (API), [`apps/web`](https://github.com/selleo/mentingo/tree/main/apps/web) (Web), [`packages`](https://github.com/selleo/mentingo/tree/main/packages) (Shared libs), [`apps/api/src`](https://github.com/selleo/mentingo/tree/main/apps/api/src) (Workers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Monorepo"]
  node_repo["mentingo<br/>workspace"]
end

subgraph group_backend["Backend"]
  node_api["API<br/>nestjs app"]
  node_storage[("Storage<br/>db layer")]
  node_dbtenant["Tenant DB"]
  node_courses["Courses<br/>learning domain"]
  node_learningpaths["Learning Paths<br/>curriculum domain"]
  node_content["Content<br/>authoring domain"]
  node_auth["Auth<br/>identity domain"]
  node_users["Users<br/>account domain"]
  node_realtime["Realtime<br/>ws subsystem"]
  node_background["Workers<br/>async jobs"]
  node_files["Files<br/>media subsystem"]
  node_live["Live Training<br/>meeting domain"]
  node_ai["AI<br/>llm subsystem"]
  node_ingestion["Ingestion<br/>embedding pipeline"]
  node_integrations["Integrations<br/>external adapters"]
end

subgraph group_frontend["Frontend"]
  node_web["Web<br/>remix app"]
  node_api_client["Typed client<br/>frontend api boundary<br/>[generated-api.ts]"]
  node_modules["Product modules<br/>ui feature modules"]
  node_guards_ui["Route guards<br/>access control ui"]
end

subgraph group_shared["Shared packages"]
  node_packages["Shared libs<br/>workspace packages"]
  node_prompts["Prompts<br/>prompt catalog"]
  node_scormpkgs["SCORM packages<br/>export/runtime"]
  node_emailtpl["Email templates<br/>template package"]
  node_sharedcore["Shared core<br/>constants/types"]
end

subgraph group_ops["Ops & delivery"]
  node_proxy["Proxy<br/>caddy"]
end

node_repo -->|"contains"| node_api
node_repo -->|"contains"| node_web
node_repo -->|"contains"| node_proxy
node_repo -->|"contains"| node_packages
node_api -->|"persists via"| node_storage
node_storage -->|"enforces"| node_dbtenant
node_api -->|"serves"| node_courses
node_api -->|"serves"| node_learningpaths
node_api -->|"serves"| node_content
node_api -->|"guards with"| node_auth
node_api -->|"manages"| node_users
node_api -->|"publishes"| node_realtime
node_api -->|"offloads"| node_background
node_api -->|"handles"| node_files
node_api -->|"integrates"| node_live
node_api -->|"implements"| node_ai
node_api -->|"feeds"| node_ingestion
node_api -->|"adapts"| node_integrations
node_web -->|"consumes"| node_api_client
node_web -->|"organizes as"| node_modules
node_web -->|"protects with"| node_guards_ui
node_web -->|"subscribes to"| node_realtime
node_web -->|"reuses"| node_packages
node_packages -->|"includes"| node_prompts
node_packages -->|"includes"| node_scormpkgs
node_packages -->|"includes"| node_emailtpl
node_packages -->|"includes"| node_sharedcore
node_background -->|"drains"| node_storage
node_background -->|"processes"| node_files
node_background -->|"syncs"| node_learningpaths
node_background -->|"supports"| node_ai

click node_api "https://github.com/selleo/mentingo/tree/main/apps/api"
click node_web "https://github.com/selleo/mentingo/tree/main/apps/web"
click node_proxy "https://github.com/selleo/mentingo/tree/main/apps/reverse-proxy"
click node_storage "https://github.com/selleo/mentingo/tree/main/apps/api/src/storage"
click node_dbtenant "https://github.com/selleo/mentingo/tree/main/apps/api/src/storage/db"
click node_courses "https://github.com/selleo/mentingo/tree/main/apps/api/src/courses"
click node_learningpaths "https://github.com/selleo/mentingo/tree/main/apps/api/src/learning-path"
click node_content "https://github.com/selleo/mentingo/tree/main/apps/api/src"
click node_auth "https://github.com/selleo/mentingo/tree/main/apps/api/src/auth"
click node_users "https://github.com/selleo/mentingo/tree/main/apps/api/src/user"
click node_realtime "https://github.com/selleo/mentingo/tree/main/apps/api/src/websocket"
click node_background "https://github.com/selleo/mentingo/tree/main/apps/api/src"
click node_files "https://github.com/selleo/mentingo/tree/main/apps/api/src/file"
click node_live "https://github.com/selleo/mentingo/tree/main/apps/api/src/live-training"
click node_ai "https://github.com/selleo/mentingo/tree/main/apps/api/src/ai"
click node_ingestion "https://github.com/selleo/mentingo/tree/main/apps/api/src/ingestion"
click node_integrations "https://github.com/selleo/mentingo/tree/main/apps/api/src/common"
click node_api_client "https://github.com/selleo/mentingo/blob/main/apps/web/app/api/generated-api.ts"
click node_modules "https://github.com/selleo/mentingo/tree/main/apps/web/app/modules"
click node_guards_ui "https://github.com/selleo/mentingo/tree/main/apps/web/app/Guards"
click node_packages "https://github.com/selleo/mentingo/tree/main/packages"
click node_prompts "https://github.com/selleo/mentingo/tree/main/packages/prompts"
click node_scormpkgs "https://github.com/selleo/mentingo/tree/main/packages/scorm-export-generator"
click node_emailtpl "https://github.com/selleo/mentingo/tree/main/packages/email-templates"
click node_sharedcore "https://github.com/selleo/mentingo/tree/main/packages/shared"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo toneBlue
class node_api,node_storage,node_dbtenant,node_courses,node_learningpaths,node_content,node_auth,node_users,node_realtime,node_background,node_files,node_live,node_ai,node_ingestion,node_integrations toneAmber
class node_web,node_api_client,node_modules,node_guards_ui toneMint
class node_packages,node_prompts,node_scormpkgs,node_emailtpl,node_sharedcore toneRose
class node_proxy toneIndigo
```

## Components

### Monorepo

Top-level workspace with runnable apps, shared packages, and deployment assets.

- **mentingo**: workspace · LMS monorepo coordinating API, web, proxy, shared packages, and delivery assets.

### Backend

NestJS API and server-side subsystems.

- [API](https://github.com/selleo/mentingo/tree/main/apps/api): nestjs app · Main backend application and domain monolith. · `apps/api`
- [Storage](https://github.com/selleo/mentingo/tree/main/apps/api/src/storage): db layer · Postgres schema, migrations, tenant-aware DB runner, and RLS enforcement. · `apps/api/src/storage`
- [Tenant DB](https://github.com/selleo/mentingo/tree/main/apps/api/src/storage/db): multi-tenant db · ALS-backed tenant resolution, request-scoped DB runner, tenant state, and RLS interceptor. · `apps/api/src/storage/db`
- [Courses](https://github.com/selleo/mentingo/tree/main/apps/api/src/courses): learning domain · Course, chapter, lesson, enrollment, SCORM, and course-generation workflows. · `apps/api/src/courses`
- [Learning Paths](https://github.com/selleo/mentingo/tree/main/apps/api/src/learning-path): curriculum domain · Learning-path composition, enrollment, export, certificate, and sync flows. · `apps/api/src/learning-path`
- [Content](https://github.com/selleo/mentingo/tree/main/apps/api/src): authoring domain · Lessons, articles, news, QA, categories, groups, and announcements around tenant learning content. · `apps/api/src`
- [Auth](https://github.com/selleo/mentingo/tree/main/apps/api/src/auth): identity domain · Local login, JWT/refresh tokens, OAuth strategies, MFA, and password flows. · `apps/api/src/auth`
- [Users](https://github.com/selleo/mentingo/tree/main/apps/api/src/user): account domain · User lifecycle, import, notifications, roles, and admin-facing account management. · `apps/api/src/user`
- [Realtime](https://github.com/selleo/mentingo/tree/main/apps/api/src/websocket): ws subsystem · WebSocket gateways, presence, live updates, and real-time publishers. · `apps/api/src/websocket`
- [Workers](https://github.com/selleo/mentingo/tree/main/apps/api/src): async jobs · Queues, cron jobs, outbox dispatch, and background processors for expensive or delayed work. · `apps/api/src`
- [Files](https://github.com/selleo/mentingo/tree/main/apps/api/src/file): media subsystem · Uploads, thumbnails, storage providers, video processing, and media delivery. · `apps/api/src/file`
- [Live Training](https://github.com/selleo/mentingo/tree/main/apps/api/src/live-training): meeting domain · LiveKit-backed sessions, announcements, recordings, and attendance flows. · `apps/api/src/live-training`
- [AI](https://github.com/selleo/mentingo/tree/main/apps/api/src/ai): llm subsystem · Chat, threads, prompts, RAG, token accounting, summaries, and judge/evaluation logic. · `apps/api/src/ai`
- [Ingestion](https://github.com/selleo/mentingo/tree/main/apps/api/src/ingestion): embedding pipeline · Document chunking, embeddings, indexing, and vector/search population. · `apps/api/src/ingestion`
- [Integrations](https://github.com/selleo/mentingo/tree/main/apps/api/src/common): external adapters · OAuth, email, S3/Bunny, Stripe, Sentry, Langfuse, Redis, and other boundary adapters. · `apps/api/src/common`

### Frontend

Remix web app and browser-facing product modules.

- [Web](https://github.com/selleo/mentingo/tree/main/apps/web): remix app · Product UI with typed API client, route modules, and client-heavy flows. · `apps/web`
- [Typed client](https://github.com/selleo/mentingo/blob/main/apps/web/app/api/generated-api.ts): frontend api boundary · Generated TypeScript client and domain hooks used by Remix features. · `apps/web/app/api/generated-api.ts`
- [Product modules](https://github.com/selleo/mentingo/tree/main/apps/web/app/modules): ui feature modules · Route-centric feature areas for auth, dashboard, courses, admin, learning, live training, and settings. · `apps/web/app/modules`
- [Route guards](https://github.com/selleo/mentingo/tree/main/apps/web/app/Guards): access control ui · Frontend access, MFA, tenant, and role-aware route protection. · `apps/web/app/Guards`

### Shared packages

Reusable libraries for prompts, SCORM, UI, types, and constants.

- [Shared libs](https://github.com/selleo/mentingo/tree/main/packages): workspace packages · Reusable packages for prompts, SCORM export/runtime, email templates, shared constants/types, and UI. · `packages`
- [Prompts](https://github.com/selleo/mentingo/tree/main/packages/prompts): prompt catalog · Generated prompt assets and templates for AI workflows. · `packages/prompts`
- [SCORM packages](https://github.com/selleo/mentingo/tree/main/packages/scorm-export-generator): export/runtime · SCORM export generator and runtime player assets. · `packages/scorm-export-generator`
- [Email templates](https://github.com/selleo/mentingo/tree/main/packages/email-templates): template package · Shared transactional email content and translations. · `packages/email-templates`
- [Shared core](https://github.com/selleo/mentingo/tree/main/packages/shared): constants/types · Cross-app constants, types, and small utilities for roles, features, content, and media. · `packages/shared`

### Ops & delivery

Container, proxy, CI, test, and deployment assets.

- [Proxy](https://github.com/selleo/mentingo/tree/main/apps/reverse-proxy): caddy · Local HTTPS and domain routing layer. · `apps/reverse-proxy`

## Connections

- mentingo → API: contains · Workspace includes the main backend app.
- mentingo → Web: contains · Workspace includes the Remix frontend.
- mentingo → Proxy: contains · Workspace includes the local reverse proxy.
- mentingo → Shared libs: contains · Workspace includes shared packages.
- API → Storage: persists via · Backend writes through migration-driven storage.
- Storage → Tenant DB: enforces · Tenant resolution and RLS are handled in the DB layer.
- API → Courses: serves · Course authoring, learning, enrollment, and SCORM flows.
- API → Learning Paths: serves · Learning-path composition and export flows.
- API → Content: serves · Content and communication domains share the monolith.
- API → Auth: guards with · Authentication and authorization are central request boundaries.
- API → Users: manages · User lifecycle and admin account operations.
- API → Realtime: publishes · WebSocket updates power live and collaborative features.
- API → Workers: offloads · Outbox, queues, workers, and cron jobs handle async work.
- API → Files: handles · Uploads, media processing, and delivery live in the backend.
- API → Live Training: integrates · Live training is a first-class backend domain.
- API → AI: implements · AI chat, RAG, summaries, and evaluation are backend features.
- API → Ingestion: feeds · Document ingestion supports AI/search pipelines.
- API → Integrations: adapts · External services are wired through boundary adapters.
- Web → Typed client: consumes · Frontend features use the generated typed API boundary.
- Web → Product modules: organizes as · Routes and UI are grouped by product module.
- Web → Route guards: protects with · Frontend mirrors backend access and tenant constraints.
- Web → Realtime: subscribes to · Course chat, live training, uploads, and sync use sockets.
- Web → Shared libs: reuses · Frontend shares types, UI primitives, and constants.
- Shared libs → Prompts: includes · Prompt templates for AI features.
- Shared libs → SCORM packages: includes · SCORM export generator/runtime package pair.
- Shared libs → Email templates: includes · Transactional email templates are isolated here.
- Shared libs → Shared core: includes · Common constants, types, and utilities live here.
- Workers → Storage: drains · Workers and dispatcher read/write persisted jobs and outbox records.
- Workers → Files: processes · Long-running media and import jobs run asynchronously.
- Workers → Learning Paths: syncs · Learning-path exports and course sync use workers.
- Workers → AI: supports · AI summaries, token accounting, and evaluation can run asynchronously.