# roicgovz/tobeton_backend architecture

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

- Interactive diagram: https://gitdiagram.com/roicgovz/tobeton_backend
- Repository: https://github.com/roicgovz/tobeton_backend

## Overview

TobeTon is a study-companion REST backend. Users authenticate and organize folders/cards, study flashcards or quizzes, and receive saved progress and statistics; AI features generate learning material, summaries, suggestions, and retrieval-grounded chat. The graph separates API dispatch, domain handlers, AI/RAG processing, and persistent state. README capabilities are retained even where implementation was not excerpted; those edges are documented or marked unverified rather than inferred from module names.

Main entry points: [`server.js`](https://github.com/roicgovz/tobeton_backend/blob/main/server.js) (Express server), [`db/database.js`](https://github.com/roicgovz/tobeton_backend/blob/main/db/database.js) (SQLite database), [`rag/retrieve.js`](https://github.com/roicgovz/tobeton_backend/blob/main/rag/retrieve.js) (Chunk retrieval), [`middleware/authMiddleware.js`](https://github.com/roicgovz/tobeton_backend/blob/main/middleware/authMiddleware.js) (JWT verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API entry"]
  node_server["Express server<br/>[server.js]"]
  node_authroutes["Auth routes<br/>[auth.js]"]
  node_userroutes["User routes<br/>[users.js]"]
  node_folderroutes["Folder routes<br/>[folder.js]"]
  node_cardroutes["Card routes<br/>[cards.js]"]
  node_flashroutes["Flashcard routes<br/>[flashcards.js]"]
  node_quizroutes["Quiz routes<br/>[quiz.js]"]
  node_statroutes["Statistics routes"]
  node_jwt["JWT verification<br/>[authMiddleware.js]"]
end

subgraph group_learning["Study management"]
  node_folders["Folder management"]
  node_cards["Card management<br/>[cardsController.js]"]
  node_flashcards["Flashcard study"]
  node_cardservice["Card persistence<br/>[cardService.js]"]
  node_quiz["Quiz workflow"]
  node_quizsave["Quiz persistence<br/>[quizSaveService.js]"]
end

subgraph group_ai["AI learning tools"]
  node_flashgen["Flashcard generation"]
  node_quizgen["Quiz generation<br/>[quizGenerator.js]"]
  node_summary["Summarization"]
  node_chat["RAG chatbot"]
  node_chatservice["Chat response<br/>[chatbotService.js]"]
  node_suggestions["Study suggestions"]
end

subgraph group_insights["Progress and identity"]
  node_auth["Authentication<br/>[authController.js]"]
  node_achievements["Achievements"]
  node_statistics["Study statistics"]
  node_database[("SQLite database<br/>[database.js]")]
end

subgraph group_rag["Retrieval pipeline"]
  node_ingest["Notes ingestion<br/>[ingestTXT.js]"]
  node_embed["Text embeddings<br/>[embed.js]"]
  node_vectors[("Vector store<br/>[vectorStore.js]")]
  node_retrieve["Chunk retrieval<br/>[retrieve.js]"]
  node_ragservice["Context assembly<br/>[ragService.js]"]
end

node_student(("Client"))
node_ollama{{"Local AI models"}}

node_student -->|"sends requests"| node_server
node_server -->|"mounts auth"| node_authroutes
node_server -->|"mounts users"| node_userroutes
node_server -->|"mounts folders"| node_folderroutes
node_server -->|"mounts cards"| node_cardroutes
node_server -->|"mounts flashcards"| node_flashroutes
node_server -->|"mounts quizzes"| node_quizroutes
node_server -->|"mounts statistics"| node_statroutes
node_server -->|"mounts chatbot"| node_chat
node_server -->|"mounts generator"| node_flashgen
node_server -->|"mounts summary"| node_summary
node_server -->|"mounts suggestions"| node_suggestions
node_server -->|"mounts generator"| node_quizgen
node_server -->|"ingests notes"| node_ingest
node_authroutes -->|"dispatches"| node_auth
node_userroutes -->|"dispatches"| node_auth
node_folderroutes -->|"checks token"| node_jwt
node_folderroutes -->|"dispatches"| node_folders
node_cardroutes -->|"checks token"| node_jwt
node_cardroutes -->|"dispatches"| node_cards
node_flashroutes -->|"checks token"| node_jwt
node_flashroutes -->|"dispatches"| node_flashcards
node_quizroutes -->|"checks token"| node_jwt
node_quizroutes -->|"dispatches"| node_quiz
node_statroutes -->|"checks token"| node_jwt
node_statroutes -->|"dispatches"| node_statistics
node_auth -->|"reads and writes"| node_database
node_folders -->|"reads and writes"| node_database
node_cards -->|"reads and writes"| node_database
node_flashcards -->|"reads and writes"| node_database
node_flashcards -->|"saves cards"| node_cardservice
node_cardservice -->|"writes cards"| node_database
node_quiz -->|"reads and writes"| node_database
node_quiz -->|"saves generated quizzes"| node_quizsave
node_quizsave -->|"writes quizzes"| node_database
node_statistics -->|"reads and updates"| node_database
node_achievements -->|"reads achievement data"| node_database
node_ingest -->|"embeds chunks"| node_embed
node_ingest -->|"stores vectors"| node_vectors
node_retrieve -->|"embeds query"| node_embed
node_retrieve -->|"ranks chunks"| node_vectors
node_chat -->|"gets context"| node_ragservice
node_ragservice -->|"retrieves chunks"| node_retrieve
node_chat -->|"generates reply"| node_chatservice
node_flashgen -->|"uses note context"| node_retrieve
node_quizgen -->|"uses note context"| node_retrieve
node_summary -.->|"uses context"| node_ragservice
node_suggestions -.->|"personalizes suggestions"| node_database

click node_server "https://github.com/roicgovz/tobeton_backend/blob/main/server.js"
click node_authroutes "https://github.com/roicgovz/tobeton_backend/blob/main/routes/auth.js"
click node_userroutes "https://github.com/roicgovz/tobeton_backend/blob/main/routes/users.js"
click node_folderroutes "https://github.com/roicgovz/tobeton_backend/blob/main/routes/folder.js"
click node_cardroutes "https://github.com/roicgovz/tobeton_backend/blob/main/routes/cards.js"
click node_flashroutes "https://github.com/roicgovz/tobeton_backend/blob/main/routes/flashcards.js"
click node_quizroutes "https://github.com/roicgovz/tobeton_backend/blob/main/routes/quiz.js"
click node_statroutes "https://github.com/roicgovz/tobeton_backend/blob/main/routes/statisticsRoutes.js"
click node_auth "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/authController.js"
click node_jwt "https://github.com/roicgovz/tobeton_backend/blob/main/middleware/authMiddleware.js"
click node_folders "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/folderController.js"
click node_cards "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/cardsController.js"
click node_flashcards "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/flashcardsController.js"
click node_cardservice "https://github.com/roicgovz/tobeton_backend/blob/main/services/cardService.js"
click node_quiz "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/quizzesController.js"
click node_quizsave "https://github.com/roicgovz/tobeton_backend/blob/main/services/quizSaveService.js"
click node_flashgen "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/flashcardsGenerator.js"
click node_quizgen "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/quizGenerator.js"
click node_summary "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/summaryController.js"
click node_chat "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/chatbotController.js"
click node_chatservice "https://github.com/roicgovz/tobeton_backend/blob/main/services/chatbotService.js"
click node_suggestions "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/studySuggestionsController.js"
click node_achievements "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/achievementController.js"
click node_statistics "https://github.com/roicgovz/tobeton_backend/blob/main/controllers/statisticsController.js"
click node_database "https://github.com/roicgovz/tobeton_backend/blob/main/db/database.js"
click node_ingest "https://github.com/roicgovz/tobeton_backend/blob/main/rag/ingestTXT.js"
click node_embed "https://github.com/roicgovz/tobeton_backend/blob/main/rag/embed.js"
click node_vectors "https://github.com/roicgovz/tobeton_backend/blob/main/rag/vectorStore.js"
click node_retrieve "https://github.com/roicgovz/tobeton_backend/blob/main/rag/retrieve.js"
click node_ragservice "https://github.com/roicgovz/tobeton_backend/blob/main/services/ragService.js"

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_server,node_authroutes,node_userroutes,node_folderroutes,node_cardroutes,node_flashroutes,node_quizroutes,node_statroutes,node_jwt,node_student toneBlue
class node_folders,node_cards,node_flashcards,node_cardservice,node_quiz,node_quizsave toneAmber
class node_flashgen,node_quizgen,node_summary,node_chat,node_chatservice,node_suggestions toneMint
class node_auth,node_achievements,node_statistics,node_database toneRose
class node_ingest,node_embed,node_vectors,node_retrieve,node_ragservice,node_ollama toneIndigo
```

## Components

### API entry

- [Express server](https://github.com/roicgovz/tobeton_backend/blob/main/server.js): `server.js`
- [Auth routes](https://github.com/roicgovz/tobeton_backend/blob/main/routes/auth.js): `routes/auth.js`
- [User routes](https://github.com/roicgovz/tobeton_backend/blob/main/routes/users.js): `routes/users.js`
- [Folder routes](https://github.com/roicgovz/tobeton_backend/blob/main/routes/folder.js): `routes/folder.js`
- [Card routes](https://github.com/roicgovz/tobeton_backend/blob/main/routes/cards.js): `routes/cards.js`
- [Flashcard routes](https://github.com/roicgovz/tobeton_backend/blob/main/routes/flashcards.js): `routes/flashcards.js`
- [Quiz routes](https://github.com/roicgovz/tobeton_backend/blob/main/routes/quiz.js): `routes/quiz.js`
- [Statistics routes](https://github.com/roicgovz/tobeton_backend/blob/main/routes/statisticsRoutes.js): `routes/statisticsRoutes.js`
- [JWT verification](https://github.com/roicgovz/tobeton_backend/blob/main/middleware/authMiddleware.js): `middleware/authMiddleware.js`

### Study management

- [Folder management](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/folderController.js): `controllers/folderController.js`
- [Card management](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/cardsController.js): `controllers/cardsController.js`
- [Flashcard study](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/flashcardsController.js): `controllers/flashcardsController.js`
- [Card persistence](https://github.com/roicgovz/tobeton_backend/blob/main/services/cardService.js): `services/cardService.js`
- [Quiz workflow](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/quizzesController.js): `controllers/quizzesController.js`
- [Quiz persistence](https://github.com/roicgovz/tobeton_backend/blob/main/services/quizSaveService.js): `services/quizSaveService.js`

### AI learning tools

- [Flashcard generation](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/flashcardsGenerator.js): `controllers/flashcardsGenerator.js`
- [Quiz generation](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/quizGenerator.js): `controllers/quizGenerator.js`
- [Summarization](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/summaryController.js): `controllers/summaryController.js`
- [RAG chatbot](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/chatbotController.js): `controllers/chatbotController.js`
- [Chat response](https://github.com/roicgovz/tobeton_backend/blob/main/services/chatbotService.js): `services/chatbotService.js`
- [Study suggestions](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/studySuggestionsController.js): `controllers/studySuggestionsController.js`

### Progress and identity

- [Authentication](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/authController.js): `controllers/authController.js`
- [Achievements](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/achievementController.js): `controllers/achievementController.js`
- [Study statistics](https://github.com/roicgovz/tobeton_backend/blob/main/controllers/statisticsController.js): `controllers/statisticsController.js`
- [SQLite database](https://github.com/roicgovz/tobeton_backend/blob/main/db/database.js): `db/database.js`

### Retrieval pipeline

- [Notes ingestion](https://github.com/roicgovz/tobeton_backend/blob/main/rag/ingestTXT.js): `rag/ingestTXT.js`
- [Text embeddings](https://github.com/roicgovz/tobeton_backend/blob/main/rag/embed.js): `rag/embed.js`
- [Vector store](https://github.com/roicgovz/tobeton_backend/blob/main/rag/vectorStore.js): `rag/vectorStore.js`
- [Chunk retrieval](https://github.com/roicgovz/tobeton_backend/blob/main/rag/retrieve.js): `rag/retrieve.js`
- [Context assembly](https://github.com/roicgovz/tobeton_backend/blob/main/services/ragService.js): `services/ragService.js`

### Other components

- **Client**
- **Local AI models**

## Connections

- Client → Express server: sends requests (evidence: `server.js`)
- Express server → Auth routes: mounts auth (evidence: `server.js`)
- Express server → User routes: mounts users (evidence: `server.js`)
- Express server → Folder routes: mounts folders (evidence: `server.js`)
- Express server → Card routes: mounts cards (evidence: `server.js`)
- Express server → Flashcard routes: mounts flashcards (evidence: `server.js`)
- Express server → Quiz routes: mounts quizzes (evidence: `server.js`)
- Express server → Statistics routes: mounts statistics (evidence: `server.js`)
- Express server → RAG chatbot: mounts chatbot (evidence: `server.js`)
- Express server → Flashcard generation: mounts generator (evidence: `server.js`)
- Express server → Summarization: mounts summary (evidence: `server.js`)
- Express server → Study suggestions: mounts suggestions (evidence: `server.js`)
- Express server → Quiz generation: mounts generator (evidence: `server.js`)
- Express server → Notes ingestion: ingests notes (evidence: `server.js`)
- Auth routes → Authentication: dispatches (evidence: `routes/auth.js`)
- User routes → Authentication: dispatches (evidence: `routes/users.js`)
- Folder routes → JWT verification: checks token (evidence: `routes/folder.js`)
- Folder routes → Folder management: dispatches (evidence: `routes/folder.js`)
- Card routes → JWT verification: checks token (evidence: `routes/cards.js`)
- Card routes → Card management: dispatches (evidence: `routes/cards.js`)
- Flashcard routes → JWT verification: checks token (evidence: `routes/flashcards.js`)
- Flashcard routes → Flashcard study: dispatches (evidence: `routes/flashcards.js`)
- Quiz routes → JWT verification: checks token (evidence: `routes/quiz.js`)
- Quiz routes → Quiz workflow: dispatches (evidence: `routes/quiz.js`)
- Statistics routes → JWT verification: checks token (evidence: `routes/statisticsRoutes.js`)
- Statistics routes → Study statistics: dispatches (evidence: `routes/statisticsRoutes.js`)
- Authentication → SQLite database: reads and writes (evidence: `controllers/authController.js`)
- Folder management → SQLite database: reads and writes (evidence: `controllers/folderController.js`)
- Card management → SQLite database: reads and writes (evidence: `controllers/cardsController.js`)
- Flashcard study → SQLite database: reads and writes (evidence: `controllers/flashcardsController.js`)
- Flashcard study → Card persistence: saves cards (evidence: `controllers/flashcardsController.js`)
- Card persistence → SQLite database: writes cards (evidence: `services/cardService.js`)
- Quiz workflow → SQLite database: reads and writes (evidence: `controllers/quizzesController.js`)
- Quiz workflow → Quiz persistence: saves generated quizzes (evidence: `controllers/quizzesController.js`)
- Quiz persistence → SQLite database: writes quizzes (evidence: `services/quizSaveService.js`)
- Study statistics → SQLite database: reads and updates (evidence: `controllers/statisticsController.js`)
- Achievements → SQLite database: reads achievement data (evidence: `controllers/achievementController.js`)
- Notes ingestion → Text embeddings: embeds chunks (evidence: `rag/ingestTXT.js`)
- Notes ingestion → Vector store: stores vectors (evidence: `rag/ingestTXT.js`)
- Chunk retrieval → Text embeddings: embeds query (evidence: `rag/retrieve.js`)
- Chunk retrieval → Vector store: ranks chunks (evidence: `rag/retrieve.js`)
- RAG chatbot → Context assembly: gets context (evidence: `controllers/chatbotController.js`)
- Context assembly → Chunk retrieval: retrieves chunks (evidence: `services/ragService.js`)
- RAG chatbot → Chat response: generates reply (evidence: `controllers/chatbotController.js`)
- Flashcard generation → Chunk retrieval: uses note context (evidence: `controllers/flashcardsGenerator.js`)
- Quiz generation → Chunk retrieval: uses note context (evidence: `controllers/quizGenerator.js`)
- Summarization → Context assembly: uses context
- Study suggestions → SQLite database: personalizes suggestions
