# c1oudreamw/qlu-toolbox architecture

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

- Interactive diagram: https://gitdiagram.com/c1oudreamw/qlu-toolbox
- Repository: https://github.com/c1oudreamw/qlu-toolbox

## Overview

LumaTile is a local-first campus utility for desktop and Android. The main desktop flow is student → Vue tool page → Electron/Python bridge → browser-backed school-system task → locally validated export; GPA and credit-progress views then process data locally. Android provides parallel schedule, grade-export, GPA, and credit-progress workflows through a Vue UI and native WebView/file handling. The README documents major capabilities beyond the sampled code; those relationships are labeled as documented rather than inferred from unseen calls.

Main entry points: [`qlu_toolbox/bridge.py`](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/bridge.py) (Python bridge), [`src/App.vue`](https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/App.vue) (Desktop workspace), [`apps/mobile/src/App.vue`](https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/src/App.vue) (Mobile workspace), [`src/pages/GradeExportPage.vue`](https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/GradeExportPage.vue) (Grade export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop client"]
  node_desktopui["Desktop workspace<br/>[App.vue]"]
  node_exportpage["Grade export"]
  node_gpaui["GPA calculator"]
  node_creditui["Credit progress"]
  node_scheduleui["Schedule manager<br/>[SchedulePage.vue]"]
  node_tasksui["Task history<br/>[TasksPage.vue]"]
  node_electron["Electron IPC<br/>[bridge.ts]"]
end

subgraph group_backend["Desktop task backend"]
  node_pybridge["Python bridge<br/>[bridge.py]"]
  node_gradeworker["Grade export worker<br/>[worker.py]"]
  node_gradeservice["Grade browser service<br/>[service.py]"]
  node_schedworker["Schedule import worker<br/>[worker.py]"]
  node_schedservice["Schedule import service<br/>[service.py]"]
  node_creditworker["Credit report worker<br/>[worker.py]"]
  node_creditservice["Credit report service<br/>[service.py]"]
end

subgraph group_mobile["Android client"]
  node_mobileapp["Mobile workspace<br/>[App.vue]"]
  node_mobileschedule["Mobile schedule<br/>[SchedulePage.vue]"]
  node_mobilecredit["Mobile credit report"]
  node_mobilegpa["Mobile GPA parser<br/>[gpaWorker.ts]"]
  node_gradeplugin["Grade WebView plugin"]
  node_gradetasks[("Grade task recovery")]
  node_widget["Schedule widget"]
end

subgraph group_domain["Academic domain"]
  node_academic["Academic calculations<br/>[credit.ts]"]
  node_schedulefiles["Schedule formats<br/>[domain.py]"]
end

subgraph group_localdata["Local state"]
  node_settings["Settings and paths<br/>[paths.py]"]
  node_scheduledata[("Schedule storage<br/>[schedules.py]")]
  node_tasksdata[("Task records<br/>[tasks.py]")]
end

node_student(("Student"))

node_student -->|"uses"| node_desktopui
node_desktopui -->|"opens"| node_exportpage
node_desktopui -->|"opens"| node_gpaui
node_desktopui -->|"opens"| node_creditui
node_desktopui -->|"opens"| node_scheduleui
node_desktopui -->|"opens"| node_tasksui
node_exportpage -.->|"invokes"| node_electron
node_electron -->|"forwards IPC"| node_pybridge
node_pybridge -->|"starts worker"| node_gradeworker
node_gradeworker -->|"runs"| node_gradeservice
node_gradeservice -->|"validates workbook"| node_academic
node_pybridge -.->|"starts worker"| node_schedworker
node_schedworker -->|"runs"| node_schedservice
node_schedservice -->|"parses schedule"| node_schedulefiles
node_pybridge -.->|"starts worker"| node_creditworker
node_creditworker -->|"runs"| node_creditservice
node_creditservice -.->|"collects progress data"| node_academic
node_student -->|"uses"| node_mobileapp
node_mobileapp -->|"shows schedule"| node_mobileschedule
node_mobileapp -->|"shows credit report"| node_mobilecredit
node_mobileapp -->|"parses GPA input"| node_mobilegpa
node_mobileapp -.->|"requests native export"| node_gradeplugin
node_gradeplugin -.->|"records task state"| node_gradetasks
node_mobileapp -.->|"refreshes widget"| node_widget
node_pybridge -->|"reads and writes"| node_scheduledata
node_pybridge -->|"records tasks"| node_tasksdata
node_pybridge -->|"uses app paths"| node_settings

click node_desktopui "https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/App.vue"
click node_exportpage "https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/GradeExportPage.vue"
click node_gpaui "https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/GPACalculatorPage.vue"
click node_creditui "https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/CreditReportPage.vue"
click node_scheduleui "https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/SchedulePage.vue"
click node_tasksui "https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/TasksPage.vue"
click node_electron "https://github.com/c1oudreamw/qlu-toolbox/blob/main/electron/bridge.ts"
click node_pybridge "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/bridge.py"
click node_gradeworker "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/grade_export/worker.py"
click node_gradeservice "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/grade_export/service.py"
click node_schedworker "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/schedule_import/worker.py"
click node_schedservice "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/schedule_import/service.py"
click node_creditworker "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/credit_report/worker.py"
click node_creditservice "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/credit_report/service.py"
click node_academic "https://github.com/c1oudreamw/qlu-toolbox/blob/main/packages/academic-core/src/credit.ts"
click node_schedulefiles "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/schedule_io/domain.py"
click node_mobileapp "https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/src/App.vue"
click node_mobileschedule "https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/src/SchedulePage.vue"
click node_mobilecredit "https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/src/CreditReportPage.vue"
click node_mobilegpa "https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/src/gpaWorker.ts"
click node_gradeplugin "https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/android/app/src/main/java/io/github/c1oudreamw/lumatile/GradeExportPlugin.kt"
click node_gradetasks "https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/android/app/src/main/java/io/github/c1oudreamw/lumatile/GradeTaskRepository.kt"
click node_widget "https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/android/app/src/main/java/io/github/c1oudreamw/lumatile/ScheduleWidgetService.kt"
click node_settings "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/core/paths.py"
click node_scheduledata "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/core/schedules.py"
click node_tasksdata "https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/core/tasks.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_desktopui,node_exportpage,node_gpaui,node_creditui,node_scheduleui,node_tasksui,node_electron toneBlue
class node_pybridge,node_gradeworker,node_gradeservice,node_schedworker,node_schedservice,node_creditworker,node_creditservice toneAmber
class node_mobileapp,node_mobileschedule,node_mobilecredit,node_mobilegpa,node_gradeplugin,node_gradetasks,node_widget toneMint
class node_academic,node_schedulefiles toneRose
class node_settings,node_scheduledata,node_tasksdata,node_student toneIndigo
```

## Components

### Desktop client

- [Desktop workspace](https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/App.vue): `src/App.vue`
- [Grade export](https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/GradeExportPage.vue): `src/pages/GradeExportPage.vue`
- [GPA calculator](https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/GPACalculatorPage.vue): `src/pages/GPACalculatorPage.vue`
- [Credit progress](https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/CreditReportPage.vue): `src/pages/CreditReportPage.vue`
- [Schedule manager](https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/SchedulePage.vue): `src/pages/SchedulePage.vue`
- [Task history](https://github.com/c1oudreamw/qlu-toolbox/blob/main/src/pages/TasksPage.vue): `src/pages/TasksPage.vue`
- [Electron IPC](https://github.com/c1oudreamw/qlu-toolbox/blob/main/electron/bridge.ts): `electron/bridge.ts`

### Desktop task backend

- [Python bridge](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/bridge.py): `qlu_toolbox/bridge.py`
- [Grade export worker](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/grade_export/worker.py): `qlu_toolbox/modules/grade_export/worker.py`
- [Grade browser service](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/grade_export/service.py): `qlu_toolbox/modules/grade_export/service.py`
- [Schedule import worker](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/schedule_import/worker.py): `qlu_toolbox/modules/schedule_import/worker.py`
- [Schedule import service](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/schedule_import/service.py): `qlu_toolbox/modules/schedule_import/service.py`
- [Credit report worker](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/credit_report/worker.py): `qlu_toolbox/modules/credit_report/worker.py`
- [Credit report service](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/credit_report/service.py): `qlu_toolbox/modules/credit_report/service.py`

### Android client

- [Mobile workspace](https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/src/App.vue): `apps/mobile/src/App.vue`
- [Mobile schedule](https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/src/SchedulePage.vue): `apps/mobile/src/SchedulePage.vue`
- [Mobile credit report](https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/src/CreditReportPage.vue): `apps/mobile/src/CreditReportPage.vue`
- [Mobile GPA parser](https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/src/gpaWorker.ts): `apps/mobile/src/gpaWorker.ts`
- [Grade WebView plugin](https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/android/app/src/main/java/io/github/c1oudreamw/lumatile/GradeExportPlugin.kt): `apps/mobile/android/app/src/main/java/io/github/c1oudreamw/lumatile/GradeExportPlugin.kt`
- [Grade task recovery](https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/android/app/src/main/java/io/github/c1oudreamw/lumatile/GradeTaskRepository.kt): `apps/mobile/android/app/src/main/java/io/github/c1oudreamw/lumatile/GradeTaskRepository.kt`
- [Schedule widget](https://github.com/c1oudreamw/qlu-toolbox/blob/main/apps/mobile/android/app/src/main/java/io/github/c1oudreamw/lumatile/ScheduleWidgetService.kt): `apps/mobile/android/app/src/main/java/io/github/c1oudreamw/lumatile/ScheduleWidgetService.kt`

### Academic domain

- [Academic calculations](https://github.com/c1oudreamw/qlu-toolbox/blob/main/packages/academic-core/src/credit.ts): `packages/academic-core/src/credit.ts`
- [Schedule formats](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/modules/schedule_io/domain.py): `qlu_toolbox/modules/schedule_io/domain.py`

### Local state

- [Settings and paths](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/core/paths.py): `qlu_toolbox/core/paths.py`
- [Schedule storage](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/core/schedules.py): `qlu_toolbox/core/schedules.py`
- [Task records](https://github.com/c1oudreamw/qlu-toolbox/blob/main/qlu_toolbox/core/tasks.py): `qlu_toolbox/core/tasks.py`

### Other components

- **Student**

## Connections

- Student → Desktop workspace: uses (evidence: `README.md`)
- Desktop workspace → Grade export: opens (evidence: `src/App.vue`)
- Desktop workspace → GPA calculator: opens (evidence: `src/App.vue`)
- Desktop workspace → Credit progress: opens (evidence: `src/App.vue`)
- Desktop workspace → Schedule manager: opens (evidence: `src/App.vue`)
- Desktop workspace → Task history: opens (evidence: `src/App.vue`)
- Grade export → Electron IPC: invokes
- Electron IPC → Python bridge: forwards IPC
- Python bridge → Grade export worker: starts worker (evidence: `qlu_toolbox/bridge.py`)
- Grade export worker → Grade browser service: runs (evidence: `qlu_toolbox/modules/grade_export/worker.py`)
- Grade browser service → Academic calculations: validates workbook (evidence: `qlu_toolbox/modules/grade_export/service.py`)
- Python bridge → Schedule import worker: starts worker
- Schedule import worker → Schedule import service: runs (evidence: `qlu_toolbox/modules/schedule_import/worker.py`)
- Schedule import service → Schedule formats: parses schedule (evidence: `qlu_toolbox/modules/schedule_import/service.py`)
- Python bridge → Credit report worker: starts worker
- Credit report worker → Credit report service: runs (evidence: `qlu_toolbox/modules/credit_report/worker.py`)
- Credit report service → Academic calculations: collects progress data
- Student → Mobile workspace: uses (evidence: `README.md`)
- Mobile workspace → Mobile schedule: shows schedule (evidence: `apps/mobile/src/App.vue`)
- Mobile workspace → Mobile credit report: shows credit report (evidence: `apps/mobile/src/App.vue`)
- Mobile workspace → Mobile GPA parser: parses GPA input (evidence: `apps/mobile/src/App.vue`)
- Mobile workspace → Grade WebView plugin: requests native export
- Grade WebView plugin → Grade task recovery: records task state
- Mobile workspace → Schedule widget: refreshes widget
- Python bridge → Schedule storage: reads and writes (evidence: `qlu_toolbox/bridge.py`)
- Python bridge → Task records: records tasks (evidence: `qlu_toolbox/bridge.py`)
- Python bridge → Settings and paths: uses app paths (evidence: `qlu_toolbox/bridge.py`)
