# kwiteegaylah/gradedesk architecture

> Architecture diagram of the GitHub repository kwiteegaylah/gradedesk, 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/kwiteegaylah/gradedesk
- Repository: https://github.com/kwiteegaylah/gradedesk

## Overview

GradeDesk is an offline Windows grade-recording app for WVSTU instructors. Instructors enter rosters, assessments, attendance, and raw marks; the app computes transmuted and weighted term and final grades, supports review and sorting, and exports submission-ready Excel workbooks. It also autosaves locally, supports JSON backup/restore, and checks for updates online. The main process owns IPC and storage, while the gradebook joins persisted inputs to the calculation engine. Renderer-to-main wiring is supported by the main-process description; unsampled renderer internals are not expanded.

Main entry points: [`src/engine/index.js`](https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/index.js) (Calculation facade), [`src/renderer/app.js`](https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/app.js) (GradeDesk screens), [`src/main.js`](https://github.com/kwiteegaylah/gradedesk/blob/main/src/main.js) (IPC and app host), [`src/data/gradebook.js`](https://github.com/kwiteegaylah/gradedesk/blob/main/src/data/gradebook.js) (Course gradebook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Instructor interface"]
  node_ui["GradeDesk screens<br/>[app.js]"]
  node_sorting["Sorting<br/>[sorting.js]"]
  node_guide["User guide<br/>[guide.js]"]
  node_ui_dates["Date helpers<br/>[dates.js]"]
  node_ui_presets["Preset interface<br/>[presets.js]"]
end

subgraph group_runtime["Application runtime"]
  node_main["IPC and app host<br/>[main.js]"]
  node_gradebook["Course gradebook<br/>[gradebook.js]"]
end

subgraph group_calculation["Grade calculation"]
  node_engine["Calculation facade<br/>[index.js]"]
  node_grades["Grade calculations<br/>[grades.js]"]
  node_transmutation["Score transmutation<br/>[transmutation.js]"]
  node_policy["Assessment policy<br/>[policy.js]"]
  node_roster["Roster parsing<br/>[roster.js]"]
  node_engine_dates["Date logic<br/>[dates.js]"]
  node_engine_presets["Preset logic<br/>[presets.js]"]
  node_tables["Transmutation tables"]
end

subgraph group_persistence["Local data"]
  node_store[("SQLite store<br/>[store.js]")]
  node_backup["Backup and restore<br/>[backup.js]"]
end

subgraph group_delivery["Exports and updates"]
  node_excel["Excel workbooks<br/>[excel.js]"]
  node_updates["Update manager<br/>[updates.js]"]
end

node_instructor(("Instructor"))
node_github["GitHub releases"]

node_instructor -->|"enters grades"| node_ui
node_ui -->|"requests via IPC"| node_main
node_main -->|"reads and writes"| node_store
node_main -->|"requests computation"| node_gradebook
node_gradebook -->|"loads course data"| node_store
node_gradebook -->|"computes grades"| node_engine
node_engine -->|"re-exports"| node_transmutation
node_engine -->|"re-exports"| node_grades
node_engine -->|"re-exports"| node_policy
node_engine -->|"re-exports"| node_roster
node_engine -->|"re-exports"| node_engine_dates
node_engine -->|"re-exports"| node_engine_presets
node_grades -->|"looks up scores"| node_transmutation
node_main -->|"generates exports"| node_excel
node_excel -->|"uses grade results"| node_engine
node_main -->|"handles backup"| node_backup
node_backup -->|"serializes database"| node_store
node_main -->|"starts update check"| node_updates
node_updates -->|"checks releases"| node_github
node_ui -.->|"offers sorting"| node_sorting
node_ui -.->|"opens guide"| node_guide
node_ui -.->|"uses date helpers"| node_ui_dates
node_ui -.->|"uses preset interface"| node_ui_presets
node_engine -->|"accepts injected tables"| node_tables

click node_ui "https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/app.js"
click node_sorting "https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/sorting.js"
click node_guide "https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/guide.js"
click node_ui_dates "https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/dates.js"
click node_ui_presets "https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/presets.js"
click node_main "https://github.com/kwiteegaylah/gradedesk/blob/main/src/main.js"
click node_gradebook "https://github.com/kwiteegaylah/gradedesk/blob/main/src/data/gradebook.js"
click node_store "https://github.com/kwiteegaylah/gradedesk/blob/main/src/data/store.js"
click node_backup "https://github.com/kwiteegaylah/gradedesk/blob/main/src/data/backup.js"
click node_engine "https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/index.js"
click node_grades "https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/grades.js"
click node_transmutation "https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/transmutation.js"
click node_policy "https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/policy.js"
click node_roster "https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/roster.js"
click node_engine_dates "https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/dates.js"
click node_engine_presets "https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/presets.js"
click node_tables "https://github.com/kwiteegaylah/gradedesk/blob/main/data/transmutation_tables.json"
click node_excel "https://github.com/kwiteegaylah/gradedesk/blob/main/src/export/excel.js"
click node_updates "https://github.com/kwiteegaylah/gradedesk/blob/main/src/updates.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_ui,node_sorting,node_guide,node_ui_dates,node_ui_presets toneBlue
class node_main,node_gradebook toneAmber
class node_engine,node_grades,node_transmutation,node_policy,node_roster,node_engine_dates,node_engine_presets,node_tables toneMint
class node_store,node_backup toneRose
class node_excel,node_updates,node_instructor,node_github toneIndigo
```

## Components

### Instructor interface

- [GradeDesk screens](https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/app.js): `src/renderer/app.js`
- [Sorting](https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/sorting.js): `src/renderer/sorting.js`
- [User guide](https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/guide.js): `src/renderer/guide.js`
- [Date helpers](https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/dates.js): `src/renderer/dates.js`
- [Preset interface](https://github.com/kwiteegaylah/gradedesk/blob/main/src/renderer/presets.js): `src/renderer/presets.js`

### Application runtime

- [IPC and app host](https://github.com/kwiteegaylah/gradedesk/blob/main/src/main.js): `src/main.js`
- [Course gradebook](https://github.com/kwiteegaylah/gradedesk/blob/main/src/data/gradebook.js): `src/data/gradebook.js`

### Grade calculation

- [Calculation facade](https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/index.js): `src/engine/index.js`
- [Grade calculations](https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/grades.js): `src/engine/grades.js`
- [Score transmutation](https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/transmutation.js): `src/engine/transmutation.js`
- [Assessment policy](https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/policy.js): `src/engine/policy.js`
- [Roster parsing](https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/roster.js): `src/engine/roster.js`
- [Date logic](https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/dates.js): `src/engine/dates.js`
- [Preset logic](https://github.com/kwiteegaylah/gradedesk/blob/main/src/engine/presets.js): `src/engine/presets.js`
- [Transmutation tables](https://github.com/kwiteegaylah/gradedesk/blob/main/data/transmutation_tables.json): `data/transmutation_tables.json`

### Local data

- [SQLite store](https://github.com/kwiteegaylah/gradedesk/blob/main/src/data/store.js): `src/data/store.js`
- [Backup and restore](https://github.com/kwiteegaylah/gradedesk/blob/main/src/data/backup.js): `src/data/backup.js`

### Exports and updates

- [Excel workbooks](https://github.com/kwiteegaylah/gradedesk/blob/main/src/export/excel.js): `src/export/excel.js`
- [Update manager](https://github.com/kwiteegaylah/gradedesk/blob/main/src/updates.js): `src/updates.js`

### Other components

- **Instructor**
- **GitHub releases**

## Connections

- Instructor → GradeDesk screens: enters grades (evidence: `README.md`)
- GradeDesk screens → IPC and app host: requests via IPC (evidence: `src/main.js`)
- IPC and app host → SQLite store: reads and writes (evidence: `src/main.js`)
- IPC and app host → Course gradebook: requests computation (evidence: `src/main.js`)
- Course gradebook → SQLite store: loads course data (evidence: `src/data/gradebook.js`)
- Course gradebook → Calculation facade: computes grades (evidence: `src/data/gradebook.js`)
- Calculation facade → Score transmutation: re-exports (evidence: `src/engine/index.js`)
- Calculation facade → Grade calculations: re-exports (evidence: `src/engine/index.js`)
- Calculation facade → Assessment policy: re-exports (evidence: `src/engine/index.js`)
- Calculation facade → Roster parsing: re-exports (evidence: `src/engine/index.js`)
- Calculation facade → Date logic: re-exports (evidence: `src/engine/index.js`)
- Calculation facade → Preset logic: re-exports (evidence: `src/engine/index.js`)
- Grade calculations → Score transmutation: looks up scores (evidence: `src/engine/grades.js`)
- IPC and app host → Excel workbooks: generates exports (evidence: `src/main.js`)
- Excel workbooks → Calculation facade: uses grade results (evidence: `src/export/excel.js`)
- IPC and app host → Backup and restore: handles backup (evidence: `src/main.js`)
- Backup and restore → SQLite store: serializes database (evidence: `src/data/backup.js`)
- IPC and app host → Update manager: starts update check (evidence: `src/main.js`)
- Update manager → GitHub releases: checks releases (evidence: `src/updates.js`)
- GradeDesk screens → Sorting: offers sorting
- GradeDesk screens → User guide: opens guide
- GradeDesk screens → Date helpers: uses date helpers
- GradeDesk screens → Preset interface: uses preset interface
- Calculation facade → Transmutation tables: accepts injected tables (evidence: `src/engine/index.js`)
