# aksofttech/ai-backend architecture

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

- Interactive diagram: https://gitdiagram.com/aksofttech/ai-backend
- Repository: https://github.com/aksofttech/ai-backend

## Overview

This is a multi-tenant education backend for schools, teachers, and students. Its core content workflow is managing books and chapters, ingesting textbook PDFs into searchable chunks, then searching or chatting over that material; AI authoring tools also retrieve curriculum context before generating teaching materials. The API includes authentication and role-based access, curriculum and user management, assignments, quizzes, lectures, and an e-library, plus PDF/PPTX compilation. The graph includes major subsystems from the tree, but links are limited where sampled source did not establish their wiring.

Main entry points: [`src/modules/rag-engine/rag-engine.service.ts`](https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/rag-engine.service.ts) (RAG orchestration), [`src/modules/auth/auth.service.ts`](https://github.com/aksofttech/ai-backend/blob/main/src/modules/auth/auth.service.ts) (Authentication), [`src/modules/ai-tools/ai-orchestrator.service.ts`](https://github.com/aksofttech/ai-backend/blob/main/src/modules/ai-tools/ai-orchestrator.service.ts) (Generation orchestration), [`src/database/entities/tenant.entity.ts`](https://github.com/aksofttech/ai-backend/blob/main/src/database/entities/tenant.entity.ts) (Tenant and users)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and tenancy"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_users["User management"]
  node_tenant[("Tenant and users<br/>[tenant.entity.ts]")]
end

subgraph group_learning["Learning workflows"]
  node_assignments["Assignments"]
  node_quiz["Quizzes and results<br/>[quiz.controller.ts]"]
  node_lectures["Lectures"]
  node_elibrary["E-library"]
end

subgraph group_knowledge["Curriculum knowledge"]
  node_curriculum["Curriculum API"]
  node_ragapi["RAG API"]
  node_rag["RAG orchestration"]
  node_pdfextract["PDF extraction"]
  node_chapterdetect["Chapter detection"]
  node_chunking["Text chunking"]
  node_embedding["Embeddings"]
  node_vectorsearch["Vector search"]
  node_contentdb[("Curriculum chunks")]
end

subgraph group_generation["AI and output"]
  node_aitools["AI authoring API"]
  node_orchestrator["Generation orchestration"]
  node_toolservices["Teaching content tools"]
  node_chatmodel["Generative AI service"]
  node_compiler["Document compiler"]
end

node_client(("API user"))
node_postgres[("PostgreSQL")]
node_embeddingapi{{"Embedding provider"}}

node_client -->|"signs up or logs in"| node_auth
node_auth -->|"looks up or creates"| node_users
node_auth -->|"creates tenant"| node_tenant
node_auth -->|"returns JWT"| node_client
node_client -->|"manages curriculum"| node_curriculum
node_client -->|"ingests, searches, chats"| node_ragapi
node_ragapi -->|"dispatches requests"| node_rag
node_rag -->|"extracts PDF text"| node_pdfextract
node_rag -->|"identifies chapters"| node_chapterdetect
node_rag -->|"splits text"| node_chunking
node_rag -->|"requests vectors"| node_embedding
node_rag -->|"searches vectors"| node_vectorsearch
node_rag -->|"reads and writes chunks"| node_contentdb
node_embedding -->|"requests embeddings"| node_embeddingapi
node_contentdb -->|"persists curriculum chunks"| node_postgres
node_tenant -->|"persists tenants and users"| node_postgres
node_client -->|"manages assignments"| node_assignments
node_client -->|"submits and views results"| node_quiz
node_client -->|"uses lectures"| node_lectures
node_client -->|"uses e-library"| node_elibrary
node_client -->|"requests teaching materials"| node_aitools
node_aitools -->|"dispatches generation"| node_orchestrator
node_orchestrator -->|"retrieves context"| node_rag
node_orchestrator -->|"selects content tool"| node_toolservices
node_toolservices -.->|"generates content"| node_chatmodel
node_client -->|"requests PDF or PPTX"| node_compiler

click node_auth "https://github.com/aksofttech/ai-backend/blob/main/src/modules/auth/auth.service.ts"
click node_users "https://github.com/aksofttech/ai-backend/blob/main/src/modules/users/users.controller.ts"
click node_tenant "https://github.com/aksofttech/ai-backend/blob/main/src/database/entities/tenant.entity.ts"
click node_curriculum "https://github.com/aksofttech/ai-backend/blob/main/src/modules/curriculum/curriculum.controller.ts"
click node_ragapi "https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/rag-engine.controller.ts"
click node_rag "https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/rag-engine.service.ts"
click node_pdfextract "https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/services/pdf-extraction.service.ts"
click node_chapterdetect "https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/services/chapter-detection.service.ts"
click node_chunking "https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/services/chunking.service.ts"
click node_embedding "https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/services/embedding.service.ts"
click node_vectorsearch "https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/services/vector-search.service.ts"
click node_contentdb "https://github.com/aksofttech/ai-backend/blob/main/src/database/entities/book-chunk.entity.ts"
click node_assignments "https://github.com/aksofttech/ai-backend/blob/main/src/modules/assignment/assignment.controller.ts"
click node_quiz "https://github.com/aksofttech/ai-backend/blob/main/src/modules/quiz/quiz.controller.ts"
click node_lectures "https://github.com/aksofttech/ai-backend/blob/main/src/modules/lectures/lectures.controller.ts"
click node_elibrary "https://github.com/aksofttech/ai-backend/blob/main/src/modules/e-library/e-library.controller.ts"
click node_aitools "https://github.com/aksofttech/ai-backend/blob/main/src/modules/ai-tools/ai-tools.controller.ts"
click node_orchestrator "https://github.com/aksofttech/ai-backend/blob/main/src/modules/ai-tools/ai-orchestrator.service.ts"
click node_toolservices "https://github.com/aksofttech/ai-backend/blob/main/src/modules/ai-tools/services/worksheet.service.ts"
click node_chatmodel "https://github.com/aksofttech/ai-backend/blob/main/src/modules/ai-tools/services/openai-chat.service.ts"
click node_compiler "https://github.com/aksofttech/ai-backend/blob/main/src/modules/compiler/compiler.controller.ts"

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_auth,node_users,node_tenant,node_client toneBlue
class node_assignments,node_quiz,node_lectures,node_elibrary,node_postgres toneAmber
class node_curriculum,node_ragapi,node_rag,node_pdfextract,node_chapterdetect,node_chunking,node_embedding,node_vectorsearch,node_contentdb toneMint
class node_aitools,node_orchestrator,node_toolservices,node_chatmodel,node_compiler toneRose
class node_embeddingapi toneIndigo
```

## Components

### Identity and tenancy

- [Authentication](https://github.com/aksofttech/ai-backend/blob/main/src/modules/auth/auth.service.ts): `src/modules/auth/auth.service.ts`
- [User management](https://github.com/aksofttech/ai-backend/blob/main/src/modules/users/users.controller.ts): `src/modules/users/users.controller.ts`
- [Tenant and users](https://github.com/aksofttech/ai-backend/blob/main/src/database/entities/tenant.entity.ts): `src/database/entities/tenant.entity.ts`

### Learning workflows

- [Assignments](https://github.com/aksofttech/ai-backend/blob/main/src/modules/assignment/assignment.controller.ts): `src/modules/assignment/assignment.controller.ts`
- [Quizzes and results](https://github.com/aksofttech/ai-backend/blob/main/src/modules/quiz/quiz.controller.ts): `src/modules/quiz/quiz.controller.ts`
- [Lectures](https://github.com/aksofttech/ai-backend/blob/main/src/modules/lectures/lectures.controller.ts): `src/modules/lectures/lectures.controller.ts`
- [E-library](https://github.com/aksofttech/ai-backend/blob/main/src/modules/e-library/e-library.controller.ts): `src/modules/e-library/e-library.controller.ts`

### Curriculum knowledge

- [Curriculum API](https://github.com/aksofttech/ai-backend/blob/main/src/modules/curriculum/curriculum.controller.ts): `src/modules/curriculum/curriculum.controller.ts`
- [RAG API](https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/rag-engine.controller.ts): `src/modules/rag-engine/rag-engine.controller.ts`
- [RAG orchestration](https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/rag-engine.service.ts): `src/modules/rag-engine/rag-engine.service.ts`
- [PDF extraction](https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/services/pdf-extraction.service.ts): `src/modules/rag-engine/services/pdf-extraction.service.ts`
- [Chapter detection](https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/services/chapter-detection.service.ts): `src/modules/rag-engine/services/chapter-detection.service.ts`
- [Text chunking](https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/services/chunking.service.ts): `src/modules/rag-engine/services/chunking.service.ts`
- [Embeddings](https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/services/embedding.service.ts): `src/modules/rag-engine/services/embedding.service.ts`
- [Vector search](https://github.com/aksofttech/ai-backend/blob/main/src/modules/rag-engine/services/vector-search.service.ts): `src/modules/rag-engine/services/vector-search.service.ts`
- [Curriculum chunks](https://github.com/aksofttech/ai-backend/blob/main/src/database/entities/book-chunk.entity.ts): `src/database/entities/book-chunk.entity.ts`

### AI and output

- [AI authoring API](https://github.com/aksofttech/ai-backend/blob/main/src/modules/ai-tools/ai-tools.controller.ts): `src/modules/ai-tools/ai-tools.controller.ts`
- [Generation orchestration](https://github.com/aksofttech/ai-backend/blob/main/src/modules/ai-tools/ai-orchestrator.service.ts): `src/modules/ai-tools/ai-orchestrator.service.ts`
- [Teaching content tools](https://github.com/aksofttech/ai-backend/blob/main/src/modules/ai-tools/services/worksheet.service.ts): `src/modules/ai-tools/services/worksheet.service.ts`
- [Generative AI service](https://github.com/aksofttech/ai-backend/blob/main/src/modules/ai-tools/services/openai-chat.service.ts): `src/modules/ai-tools/services/openai-chat.service.ts`
- [Document compiler](https://github.com/aksofttech/ai-backend/blob/main/src/modules/compiler/compiler.controller.ts): `src/modules/compiler/compiler.controller.ts`

### Other components

- **API user**
- **PostgreSQL**
- **Embedding provider**

## Connections

- API user → Authentication: signs up or logs in
- Authentication → User management: looks up or creates
- Authentication → Tenant and users: creates tenant
- Authentication → API user: returns JWT
- API user → Curriculum API: manages curriculum
- API user → RAG API: ingests, searches, chats
- RAG API → RAG orchestration: dispatches requests
- RAG orchestration → PDF extraction: extracts PDF text
- RAG orchestration → Chapter detection: identifies chapters
- RAG orchestration → Text chunking: splits text
- RAG orchestration → Embeddings: requests vectors
- RAG orchestration → Vector search: searches vectors
- RAG orchestration → Curriculum chunks: reads and writes chunks
- Embeddings → Embedding provider: requests embeddings
- Curriculum chunks → PostgreSQL: persists curriculum chunks
- Tenant and users → PostgreSQL: persists tenants and users
- API user → Assignments: manages assignments
- API user → Quizzes and results: submits and views results
- API user → Lectures: uses lectures
- API user → E-library: uses e-library
- API user → AI authoring API: requests teaching materials
- AI authoring API → Generation orchestration: dispatches generation
- Generation orchestration → RAG orchestration: retrieves context
- Generation orchestration → Teaching content tools: selects content tool
- Teaching content tools → Generative AI service: generates content
- API user → Document compiler: requests PDF or PPTX