# jl115/visual-learner architecture

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

- Interactive diagram: https://gitdiagram.com/jl115/visual-learner
- Repository: https://github.com/jl115/visual-learner

## Overview

Visual Learner is a desktop app for turning PDFs into interactive visual learning material. The principal workflow starts with a learner uploading a document, then proceeds through backend document processing and knowledge-graph creation; the UI also exposes a document library, graph exploration, quizzes, mastery progress, and achievements. The README documents the frontend feature slices and backend layering, while sampled code confirms app routing, Electron file-reading IPC, and graph assembly/persistence. Most domain-specific handler wiring and several feature implementations are not sampled, so uncertain links are omitted.

Main entry points: [`backend/app/controllers`](https://github.com/jl115/visual-learner/tree/main/backend/app/controllers) (Request orchestration), [`frontend/src/app/router.ts`](https://github.com/jl115/visual-learner/blob/main/frontend/src/app/router.ts) (App router), [`frontend/src/features/documentUpload`](https://github.com/jl115/visual-learner/tree/main/frontend/src/features/documentUpload) (Document upload), [`backend/app/repositories`](https://github.com/jl115/visual-learner/tree/main/backend/app/repositories) (Domain repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop shell"]
  node_electron["Electron main<br/>[main.ts]"]
  node_preload["Preload bridge<br/>[preload.ts]"]
end

subgraph group_frontend["Learner interface"]
  node_app["App bootstrap<br/>[main.ts]"]
  node_router["App router<br/>[router.ts]"]
  node_upload["Document upload"]
  node_library["Document library"]
  node_graphui["Knowledge graph UI"]
  node_quizui["Quiz session UI"]
  node_progressui["Mastery progress UI"]
  node_achievementsui["Achievements UI"]
end

subgraph group_api["Backend API"]
  node_uploadroute["Upload endpoint<br/>[upload.py]"]
  node_docroutes["Document endpoints<br/>[documents.py]"]
  node_graphroutes["Graph endpoints<br/>[graphs.py]"]
  node_quizroutes["Quiz endpoints<br/>[quizzes.py]"]
  node_progressroutes["Progress endpoints<br/>[progress.py]"]
  node_scoresroutes["Score endpoints<br/>[scores.py]"]
  node_controllers["Request orchestration"]
end

subgraph group_domain["Learning services"]
  node_filereader["Document reader"]
  node_nlp["Text processing<br/>[nlp_pipeline.py]"]
  node_graphservice["Graph construction<br/>[graph_service.py]"]
  node_quizservice["Quiz logic<br/>[quiz_service.py]"]
  node_scoreservice["Score and progress logic<br/>[score_service.py]"]
end

subgraph group_storage["Persistence"]
  node_repositories["Domain repositories"]
  node_database[("SQL database")]
end

node_learner(("Learner"))
node_ollama["Ollama service"]

node_learner -->|"selects PDF"| node_upload
node_learner -->|"browses documents"| node_library
node_learner -->|"explores graph"| node_graphui
node_learner -->|"takes quiz"| node_quizui
node_learner -->|"checks mastery"| node_progressui
node_learner -->|"views awards"| node_achievementsui
node_electron -->|"exposes IPC"| node_preload
node_preload -->|"provides file access"| node_upload
node_app -->|"installs"| node_router
node_router -->|"routes to"| node_upload
node_router -->|"routes to"| node_library
node_router -->|"routes to"| node_graphui
node_router -->|"routes to"| node_quizui
node_router -->|"routes to"| node_progressui
node_router -->|"routes to"| node_achievementsui
node_upload -->|"submits document"| node_uploadroute
node_library -->|"requests documents"| node_docroutes
node_graphui -->|"requests graph"| node_graphroutes
node_quizui -->|"requests quiz"| node_quizroutes
node_progressui -->|"requests progress"| node_progressroutes
node_achievementsui -.->|"requests scores"| node_scoresroutes
node_uploadroute -->|"dispatches request"| node_controllers
node_docroutes -->|"dispatches request"| node_controllers
node_graphroutes -->|"dispatches request"| node_controllers
node_quizroutes -->|"dispatches request"| node_controllers
node_progressroutes -->|"dispatches request"| node_controllers
node_scoresroutes -->|"dispatches request"| node_controllers
node_controllers -->|"processes documents"| node_filereader
node_controllers -->|"processes text"| node_nlp
node_controllers -->|"orchestrates graph"| node_graphservice
node_controllers -->|"orchestrates quizzes"| node_quizservice
node_controllers -->|"orchestrates scores"| node_scoreservice
node_graphservice -->|"persists and reads"| node_repositories
node_quizservice -->|"uses persistence"| node_repositories
node_scoreservice -->|"uses persistence"| node_repositories
node_repositories -->|"reads and writes"| node_database
node_graphservice -.->|"optional integration"| node_ollama

click node_electron "https://github.com/jl115/visual-learner/blob/main/electron/main.ts"
click node_preload "https://github.com/jl115/visual-learner/blob/main/electron/preload.ts"
click node_app "https://github.com/jl115/visual-learner/blob/main/frontend/src/app/main.ts"
click node_router "https://github.com/jl115/visual-learner/blob/main/frontend/src/app/router.ts"
click node_upload "https://github.com/jl115/visual-learner/tree/main/frontend/src/features/documentUpload"
click node_library "https://github.com/jl115/visual-learner/tree/main/frontend/src/features/documentLibrary"
click node_graphui "https://github.com/jl115/visual-learner/tree/main/frontend/src/features/knowledgeGraph"
click node_quizui "https://github.com/jl115/visual-learner/tree/main/frontend/src/features/quizSession"
click node_progressui "https://github.com/jl115/visual-learner/tree/main/frontend/src/features/masteryProgress"
click node_achievementsui "https://github.com/jl115/visual-learner/tree/main/frontend/src/features/achievements"
click node_uploadroute "https://github.com/jl115/visual-learner/blob/main/backend/app/routers/upload.py"
click node_docroutes "https://github.com/jl115/visual-learner/blob/main/backend/app/routers/documents.py"
click node_graphroutes "https://github.com/jl115/visual-learner/blob/main/backend/app/routers/graphs.py"
click node_quizroutes "https://github.com/jl115/visual-learner/blob/main/backend/app/routers/quizzes.py"
click node_progressroutes "https://github.com/jl115/visual-learner/blob/main/backend/app/routers/progress.py"
click node_scoresroutes "https://github.com/jl115/visual-learner/blob/main/backend/app/routers/scores.py"
click node_controllers "https://github.com/jl115/visual-learner/tree/main/backend/app/controllers"
click node_filereader "https://github.com/jl115/visual-learner/blob/main/backend/app/services/file_reader_service.py"
click node_nlp "https://github.com/jl115/visual-learner/blob/main/backend/app/services/nlp_pipeline.py"
click node_graphservice "https://github.com/jl115/visual-learner/blob/main/backend/app/services/graph_service.py"
click node_quizservice "https://github.com/jl115/visual-learner/blob/main/backend/app/services/quiz_service.py"
click node_scoreservice "https://github.com/jl115/visual-learner/blob/main/backend/app/services/score_service.py"
click node_repositories "https://github.com/jl115/visual-learner/tree/main/backend/app/repositories"
click node_database "https://github.com/jl115/visual-learner/tree/main/backend/app/database"

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_electron,node_preload toneBlue
class node_app,node_router,node_upload,node_library,node_graphui,node_quizui,node_progressui,node_achievementsui toneAmber
class node_uploadroute,node_docroutes,node_graphroutes,node_quizroutes,node_progressroutes,node_scoresroutes,node_controllers toneMint
class node_filereader,node_nlp,node_graphservice,node_quizservice,node_scoreservice toneRose
class node_repositories,node_database,node_learner,node_ollama toneIndigo
```

## Components

### Desktop shell

- [Electron main](https://github.com/jl115/visual-learner/blob/main/electron/main.ts): `electron/main.ts`
- [Preload bridge](https://github.com/jl115/visual-learner/blob/main/electron/preload.ts): `electron/preload.ts`

### Learner interface

- [App bootstrap](https://github.com/jl115/visual-learner/blob/main/frontend/src/app/main.ts): `frontend/src/app/main.ts`
- [App router](https://github.com/jl115/visual-learner/blob/main/frontend/src/app/router.ts): `frontend/src/app/router.ts`
- [Document upload](https://github.com/jl115/visual-learner/tree/main/frontend/src/features/documentUpload): `frontend/src/features/documentUpload`
- [Document library](https://github.com/jl115/visual-learner/tree/main/frontend/src/features/documentLibrary): `frontend/src/features/documentLibrary`
- [Knowledge graph UI](https://github.com/jl115/visual-learner/tree/main/frontend/src/features/knowledgeGraph): `frontend/src/features/knowledgeGraph`
- [Quiz session UI](https://github.com/jl115/visual-learner/tree/main/frontend/src/features/quizSession): `frontend/src/features/quizSession`
- [Mastery progress UI](https://github.com/jl115/visual-learner/tree/main/frontend/src/features/masteryProgress): `frontend/src/features/masteryProgress`
- [Achievements UI](https://github.com/jl115/visual-learner/tree/main/frontend/src/features/achievements): `frontend/src/features/achievements`

### Backend API

- [Upload endpoint](https://github.com/jl115/visual-learner/blob/main/backend/app/routers/upload.py): `backend/app/routers/upload.py`
- [Document endpoints](https://github.com/jl115/visual-learner/blob/main/backend/app/routers/documents.py): `backend/app/routers/documents.py`
- [Graph endpoints](https://github.com/jl115/visual-learner/blob/main/backend/app/routers/graphs.py): `backend/app/routers/graphs.py`
- [Quiz endpoints](https://github.com/jl115/visual-learner/blob/main/backend/app/routers/quizzes.py): `backend/app/routers/quizzes.py`
- [Progress endpoints](https://github.com/jl115/visual-learner/blob/main/backend/app/routers/progress.py): `backend/app/routers/progress.py`
- [Score endpoints](https://github.com/jl115/visual-learner/blob/main/backend/app/routers/scores.py): `backend/app/routers/scores.py`
- [Request orchestration](https://github.com/jl115/visual-learner/tree/main/backend/app/controllers): `backend/app/controllers`

### Learning services

- [Document reader](https://github.com/jl115/visual-learner/blob/main/backend/app/services/file_reader_service.py): `backend/app/services/file_reader_service.py`
- [Text processing](https://github.com/jl115/visual-learner/blob/main/backend/app/services/nlp_pipeline.py): `backend/app/services/nlp_pipeline.py`
- [Graph construction](https://github.com/jl115/visual-learner/blob/main/backend/app/services/graph_service.py): `backend/app/services/graph_service.py`
- [Quiz logic](https://github.com/jl115/visual-learner/blob/main/backend/app/services/quiz_service.py): `backend/app/services/quiz_service.py`
- [Score and progress logic](https://github.com/jl115/visual-learner/blob/main/backend/app/services/score_service.py): `backend/app/services/score_service.py`

### Persistence

- [Domain repositories](https://github.com/jl115/visual-learner/tree/main/backend/app/repositories): `backend/app/repositories`
- [SQL database](https://github.com/jl115/visual-learner/tree/main/backend/app/database): `backend/app/database`

### Other components

- **Learner**
- **Ollama service**

## Connections

- Learner → Document upload: selects PDF
- Learner → Document library: browses documents
- Learner → Knowledge graph UI: explores graph
- Learner → Quiz session UI: takes quiz
- Learner → Mastery progress UI: checks mastery
- Learner → Achievements UI: views awards
- Electron main → Preload bridge: exposes IPC
- Preload bridge → Document upload: provides file access
- App bootstrap → App router: installs
- App router → Document upload: routes to
- App router → Document library: routes to
- App router → Knowledge graph UI: routes to
- App router → Quiz session UI: routes to
- App router → Mastery progress UI: routes to
- App router → Achievements UI: routes to
- Document upload → Upload endpoint: submits document
- Document library → Document endpoints: requests documents
- Knowledge graph UI → Graph endpoints: requests graph
- Quiz session UI → Quiz endpoints: requests quiz
- Mastery progress UI → Progress endpoints: requests progress
- Achievements UI → Score endpoints: requests scores
- Upload endpoint → Request orchestration: dispatches request
- Document endpoints → Request orchestration: dispatches request
- Graph endpoints → Request orchestration: dispatches request
- Quiz endpoints → Request orchestration: dispatches request
- Progress endpoints → Request orchestration: dispatches request
- Score endpoints → Request orchestration: dispatches request
- Request orchestration → Document reader: processes documents
- Request orchestration → Text processing: processes text
- Request orchestration → Graph construction: orchestrates graph
- Request orchestration → Quiz logic: orchestrates quizzes
- Request orchestration → Score and progress logic: orchestrates scores
- Graph construction → Domain repositories: persists and reads
- Quiz logic → Domain repositories: uses persistence
- Score and progress logic → Domain repositories: uses persistence
- Domain repositories → SQL database: reads and writes
- Graph construction → Ollama service: optional integration