# hcmuleva/els-ai architecture

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

- Interactive diagram: https://gitdiagram.com/hcmuleva/els-ai
- Repository: https://github.com/hcmuleva/els-ai

## Overview

ELS-AI is a multi-tenant learning platform: learners and educators use a React Native app to access learning activities, while backend services provide identity, learning data, media, and AI. The principal learning workflow spans content and classroom access, interactive quizzes, and learner reporting; teachers also review AI-assisted work. The AI service exposes generation jobs with validation, persistence, and streamed progress. The README documents Jev evaluation and conversational LLM support. Some subsystem internals are unsampled, so their links are shown only where the README or excerpts support them.

Main entry points: [`backend/core-api/src/server.ts`](https://github.com/hcmuleva/els-ai/blob/main/backend/core-api/src/server.ts) (Core API), [`frontend/App.tsx`](https://github.com/hcmuleva/els-ai/blob/main/frontend/App.tsx) (React Native app), [`backend/ai-service/src/generation/pipeline.ts`](https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/generation/pipeline.ts) (Content generation), [`backend/ai-service/src/server.ts`](https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/server.ts) (AI service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Learning app"]
  node_frontend["React Native app<br/>[App.tsx]"]
  node_interactive["Interactive quiz engine"]
  node_learning["Learning screens"]
end

subgraph group_core["Learning platform"]
  node_coreapi["Core API<br/>[server.ts]"]
  node_identity[("Identity &amp; tenancy")]
  node_learningdata[("Learning data services")]
  node_classroom[("Classrooms &amp; assignments")]
  node_assessment[("Questions &amp; quizzes")]
  node_chat[("Chat &amp; review")]
  node_notifications[("Notifications")]
end

subgraph group_ai["AI services"]
  node_aiservice["AI service<br/>[server.ts]"]
  node_generation["Content generation<br/>[pipeline.ts]"]
  node_generators["Type generators"]
  node_jobstore[("Generation jobs<br/>[jobStore.ts]")]
  node_llm["LLM agent router<br/>[router.ts]"]
  node_jev["Jev evaluation client<br/>[jevClient.ts]"]
end

subgraph group_infra["Shared infrastructure"]
  node_eventbus["Shared event bus<br/>[index.ts]"]
end

subgraph group_media["Media delivery"]
  node_media["Media service<br/>[server.ts]"]
  node_s3[("AWS S3")]
end

node_learner(("Learners &amp; educators"))

node_learner -->|"uses"| node_frontend
node_frontend -->|"requests learning data"| node_coreapi
node_frontend -->|"requests AI services"| node_aiservice
node_frontend -->|"plays quizzes"| node_interactive
node_coreapi -->|"routes identity"| node_identity
node_coreapi -->|"routes content"| node_learningdata
node_coreapi -->|"routes classrooms"| node_classroom
node_coreapi -->|"routes questions"| node_assessment
node_coreapi -.->|"routes chat"| node_chat
node_coreapi -.->|"routes notifications"| node_notifications
node_aiservice -.->|"routes generation"| node_generation
node_generation -->|"dispatches generation"| node_generators
node_generation -->|"updates jobs"| node_jobstore
node_generation -.->|"uses model routing"| node_llm
node_aiservice -->|"evaluates observations"| node_jev
node_media -.->|"stores assets"| node_s3
node_learningdata -.->|"publishes events"| node_eventbus

click node_frontend "https://github.com/hcmuleva/els-ai/blob/main/frontend/App.tsx"
click node_interactive "https://github.com/hcmuleva/els-ai/tree/main/frontend/src/components/quiz"
click node_learning "https://github.com/hcmuleva/els-ai/tree/main/frontend/app/(tabs)"
click node_coreapi "https://github.com/hcmuleva/els-ai/blob/main/backend/core-api/src/server.ts"
click node_identity "https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/auth"
click node_learningdata "https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/content"
click node_classroom "https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/classroom"
click node_assessment "https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/question-bank"
click node_chat "https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/chat"
click node_notifications "https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/notification"
click node_aiservice "https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/server.ts"
click node_generation "https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/generation/pipeline.ts"
click node_generators "https://github.com/hcmuleva/els-ai/tree/main/backend/ai-service/src/generation/generators"
click node_jobstore "https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/generation/jobStore.ts"
click node_llm "https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/agents/router.ts"
click node_jev "https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/services/jevClient.ts"
click node_media "https://github.com/hcmuleva/els-ai/blob/main/backend/media-service/src/server.ts"
click node_eventbus "https://github.com/hcmuleva/els-ai/blob/main/backend/shared/event-bus/src/index.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_frontend,node_interactive,node_learning toneBlue
class node_coreapi,node_identity,node_learningdata,node_classroom,node_assessment,node_chat,node_notifications toneAmber
class node_aiservice,node_generation,node_generators,node_jobstore,node_llm,node_jev toneMint
class node_eventbus toneRose
class node_media,node_s3,node_learner toneIndigo
```

## Components

### Learning app

- [React Native app](https://github.com/hcmuleva/els-ai/blob/main/frontend/App.tsx): `frontend/App.tsx`
- [Interactive quiz engine](https://github.com/hcmuleva/els-ai/tree/main/frontend/src/components/quiz): `frontend/src/components/quiz`
- [Learning screens](https://github.com/hcmuleva/els-ai/tree/main/frontend/app/(tabs)): `frontend/app/(tabs)`

### Learning platform

- [Core API](https://github.com/hcmuleva/els-ai/blob/main/backend/core-api/src/server.ts): `backend/core-api/src/server.ts`
- [Identity & tenancy](https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/auth): `backend/core-api/src/services/auth`
- [Learning data services](https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/content): `backend/core-api/src/services/content`
- [Classrooms & assignments](https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/classroom): `backend/core-api/src/services/classroom`
- [Questions & quizzes](https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/question-bank): `backend/core-api/src/services/question-bank`
- [Chat & review](https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/chat): `backend/core-api/src/services/chat`
- [Notifications](https://github.com/hcmuleva/els-ai/tree/main/backend/core-api/src/services/notification): `backend/core-api/src/services/notification`

### AI services

- [AI service](https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/server.ts): `backend/ai-service/src/server.ts`
- [Content generation](https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/generation/pipeline.ts): `backend/ai-service/src/generation/pipeline.ts`
- [Type generators](https://github.com/hcmuleva/els-ai/tree/main/backend/ai-service/src/generation/generators): `backend/ai-service/src/generation/generators`
- [Generation jobs](https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/generation/jobStore.ts): `backend/ai-service/src/generation/jobStore.ts`
- [LLM agent router](https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/agents/router.ts): `backend/ai-service/src/agents/router.ts`
- [Jev evaluation client](https://github.com/hcmuleva/els-ai/blob/main/backend/ai-service/src/services/jevClient.ts): `backend/ai-service/src/services/jevClient.ts`

### Shared infrastructure

- [Shared event bus](https://github.com/hcmuleva/els-ai/blob/main/backend/shared/event-bus/src/index.ts): `backend/shared/event-bus/src/index.ts`

### Media delivery

- [Media service](https://github.com/hcmuleva/els-ai/blob/main/backend/media-service/src/server.ts): `backend/media-service/src/server.ts`
- **AWS S3**

### Other components

- **Learners & educators**

## Connections

- Learners & educators → React Native app: uses (evidence: `README.md`)
- React Native app → Core API: requests learning data (evidence: `README.md`)
- React Native app → AI service: requests AI services (evidence: `README.md`)
- React Native app → Interactive quiz engine: plays quizzes (evidence: `README.md`)
- Core API → Identity & tenancy: routes identity (evidence: `backend/core-api/src/server.ts`)
- Core API → Learning data services: routes content (evidence: `backend/core-api/src/server.ts`)
- Core API → Classrooms & assignments: routes classrooms (evidence: `backend/core-api/src/server.ts`)
- Core API → Questions & quizzes: routes questions (evidence: `backend/core-api/src/server.ts`)
- Core API → Chat & review: routes chat (evidence: `README.md`)
- Core API → Notifications: routes notifications (evidence: `README.md`)
- AI service → Content generation: routes generation (evidence: `README.md`)
- Content generation → Type generators: dispatches generation (evidence: `backend/ai-service/src/generation/pipeline.ts`)
- Content generation → Generation jobs: updates jobs (evidence: `backend/ai-service/src/generation/pipeline.ts`)
- Content generation → LLM agent router: uses model routing (evidence: `README.md`)
- AI service → Jev evaluation client: evaluates observations (evidence: `README.md`)
- Media service → AWS S3: stores assets (evidence: `README.md`)
- Learning data services → Shared event bus: publishes events (evidence: `README.md`)
