# mostafaai10/mofid architecture

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

- Interactive diagram: https://gitdiagram.com/mostafaai10/mofid
- Repository: https://github.com/mostafaai10/mofid

## Overview

Mofid is an offline-first curriculum Q&A MVP: a student asks through the web app, the API retrieves course-scoped curriculum passages, and a local Karnak model generates a grounded answer with citations—or the API refuses when retrieval finds no relevant content. The repository also includes curriculum preparation and indexing, plus the documented teacher-upload capability. The tree has no teacher-dashboard UI or FAQ implementation, so those are not represented as implemented components; deployment scripts are omitted. Some frontend and ingestion links are based on explicit documentation because their full source was not sampled.

Main entry points: [`backend/rag.py`](https://github.com/mostafaai10/mofid/blob/main/backend/rag.py) (RAG retrieval/indexing), [`backend/app.py`](https://github.com/mostafaai10/mofid/blob/main/backend/app.py) (FastAPI endpoints), [`content/physics_grade12.json`](https://github.com/mostafaai10/mofid/blob/main/content/physics_grade12.json) (Curriculum chunks), [`webapp/app.js`](https://github.com/mostafaai10/mofid/blob/main/webapp/app.js) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_student["Student experience"]
  node_chat_ui["Chat interface<br/>[app.js]"]
  node_web_client["API client<br/>[api.js]"]
end

subgraph group_backend["Answer backend"]
  node_api["FastAPI endpoints<br/>[app.py]"]
  node_rag["RAG retrieval/indexing<br/>[rag.py]"]
  node_textnorm["Query normalization<br/>[textnorm.py]"]
  node_config["Backend settings<br/>[config.py]"]
  node_embedding_model["Embedding model"]
  node_chroma[("Chroma vector store")]
  node_karnak["Karnak inference server"]
end

subgraph group_content["Curriculum preparation"]
  node_content_file["Curriculum chunks"]
  node_extract_pdf["PDF extraction<br/>[extract_pdf.py]"]
  node_make_chunks["Chunk generation<br/>[make_chunks.py]"]
  node_review_chunks["Chunk review<br/>[review_report.py]"]
  node_validate_chunks["Chunk validation<br/>[validate_chunks.py]"]
  node_indexer["Initial index loader<br/>[index_content.py]"]
end

subgraph group_offline["Offline delivery"]
  node_offline_cache["App cache<br/>[sw.js]"]
end

node_student_actor(("Student"))
node_teacher(("Teacher content uploader"))

node_student_actor -->|"asks question"| node_chat_ui
node_chat_ui -->|"uses API"| node_web_client
node_web_client -->|"calls ask/health"| node_api
node_chat_ui -->|"registers worker"| node_offline_cache
node_api -->|"retrieves context"| node_rag
node_api -->|"indexes uploads"| node_rag
node_api -->|"requests generation"| node_karnak
node_rag -->|"embeds text"| node_embedding_model
node_rag -->|"queries and upserts"| node_chroma
node_rag -->|"checks coverage"| node_textnorm
node_rag -->|"reads settings"| node_config
node_api -->|"reads settings"| node_config
node_content_file -->|"loaded from"| node_indexer
node_indexer -->|"indexes chunks"| node_rag
node_extract_pdf -->|"provides page text"| node_make_chunks
node_make_chunks -.->|"produces draft"| node_content_file
node_content_file -->|"reviewed as input"| node_review_chunks
node_content_file -->|"validated as input"| node_validate_chunks
node_teacher -->|"uploads chunks"| node_api

click node_chat_ui "https://github.com/mostafaai10/mofid/blob/main/webapp/app.js"
click node_web_client "https://github.com/mostafaai10/mofid/blob/main/webapp/api.js"
click node_offline_cache "https://github.com/mostafaai10/mofid/blob/main/webapp/sw.js"
click node_api "https://github.com/mostafaai10/mofid/blob/main/backend/app.py"
click node_rag "https://github.com/mostafaai10/mofid/blob/main/backend/rag.py"
click node_textnorm "https://github.com/mostafaai10/mofid/blob/main/backend/textnorm.py"
click node_config "https://github.com/mostafaai10/mofid/blob/main/backend/config.py"
click node_content_file "https://github.com/mostafaai10/mofid/blob/main/content/physics_grade12.json"
click node_extract_pdf "https://github.com/mostafaai10/mofid/blob/main/tools/extract_pdf.py"
click node_make_chunks "https://github.com/mostafaai10/mofid/blob/main/tools/make_chunks.py"
click node_review_chunks "https://github.com/mostafaai10/mofid/blob/main/tools/review_report.py"
click node_validate_chunks "https://github.com/mostafaai10/mofid/blob/main/tools/validate_chunks.py"
click node_indexer "https://github.com/mostafaai10/mofid/blob/main/backend/index_content.py"

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_chat_ui,node_web_client toneBlue
class node_api,node_rag,node_textnorm,node_config,node_embedding_model,node_chroma,node_karnak toneAmber
class node_content_file,node_extract_pdf,node_make_chunks,node_review_chunks,node_validate_chunks,node_indexer toneMint
class node_offline_cache toneRose
class node_student_actor,node_teacher toneIndigo
```

## Components

### Student experience

- [Chat interface](https://github.com/mostafaai10/mofid/blob/main/webapp/app.js): `webapp/app.js`
- [API client](https://github.com/mostafaai10/mofid/blob/main/webapp/api.js): `webapp/api.js`

### Answer backend

- [FastAPI endpoints](https://github.com/mostafaai10/mofid/blob/main/backend/app.py): `backend/app.py`
- [RAG retrieval/indexing](https://github.com/mostafaai10/mofid/blob/main/backend/rag.py): `backend/rag.py`
- [Query normalization](https://github.com/mostafaai10/mofid/blob/main/backend/textnorm.py): `backend/textnorm.py`
- [Backend settings](https://github.com/mostafaai10/mofid/blob/main/backend/config.py): `backend/config.py`
- **Embedding model**
- **Chroma vector store**
- **Karnak inference server**

### Curriculum preparation

- [Curriculum chunks](https://github.com/mostafaai10/mofid/blob/main/content/physics_grade12.json): `content/physics_grade12.json`
- [PDF extraction](https://github.com/mostafaai10/mofid/blob/main/tools/extract_pdf.py): `tools/extract_pdf.py`
- [Chunk generation](https://github.com/mostafaai10/mofid/blob/main/tools/make_chunks.py): `tools/make_chunks.py`
- [Chunk review](https://github.com/mostafaai10/mofid/blob/main/tools/review_report.py): `tools/review_report.py`
- [Chunk validation](https://github.com/mostafaai10/mofid/blob/main/tools/validate_chunks.py): `tools/validate_chunks.py`
- [Initial index loader](https://github.com/mostafaai10/mofid/blob/main/backend/index_content.py): `backend/index_content.py`

### Offline delivery

- [App cache](https://github.com/mostafaai10/mofid/blob/main/webapp/sw.js): `webapp/sw.js`

### Other components

- **Student**
- **Teacher content uploader**

## Connections

- Student → Chat interface: asks question (evidence: `README.md`)
- Chat interface → API client: uses API (evidence: `webapp/app.js`)
- API client → FastAPI endpoints: calls ask/health (evidence: `webapp/api.js`)
- Chat interface → App cache: registers worker (evidence: `webapp/app.js`)
- FastAPI endpoints → RAG retrieval/indexing: retrieves context (evidence: `backend/app.py`)
- FastAPI endpoints → RAG retrieval/indexing: indexes uploads (evidence: `backend/app.py`)
- FastAPI endpoints → Karnak inference server: requests generation (evidence: `backend/app.py`)
- RAG retrieval/indexing → Embedding model: embeds text (evidence: `backend/rag.py`)
- RAG retrieval/indexing → Chroma vector store: queries and upserts (evidence: `backend/rag.py`)
- RAG retrieval/indexing → Query normalization: checks coverage (evidence: `backend/rag.py`)
- RAG retrieval/indexing → Backend settings: reads settings (evidence: `backend/rag.py`)
- FastAPI endpoints → Backend settings: reads settings (evidence: `backend/app.py`)
- Curriculum chunks → Initial index loader: loaded from (evidence: `backend/index_content.py`)
- Initial index loader → RAG retrieval/indexing: indexes chunks (evidence: `backend/index_content.py`)
- PDF extraction → Chunk generation: provides page text (evidence: `tools/make_chunks.py`)
- Chunk generation → Curriculum chunks: produces draft
- Curriculum chunks → Chunk review: reviewed as input (evidence: `tools/review_report.py`)
- Curriculum chunks → Chunk validation: validated as input (evidence: `tools/validate_chunks.py`)
- Teacher content uploader → FastAPI endpoints: uploads chunks (evidence: `README.md`)
