# yujiankoh/modulo architecture

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

- Interactive diagram: https://gitdiagram.com/yujiankoh/modulo
- Repository: https://github.com/yujiankoh/modulo

## Overview

modulo is a cross-platform academic companion: students organize coursework, turn timetable images into editable schedules, track study sessions, and build a reward city. The web entry point explicitly coordinates sign-in and local/Drive storage selection; the README documents parallel mobile capabilities. The tree and excerpts support the major feature areas, but most Android and web feature wiring is unsampled, so those internal links are omitted. The timetable proxy’s Gemini integration is explicit in its source.

Main entry points: [`web/main.js`](https://github.com/yujiankoh/modulo/blob/main/web/main.js) (Web entry), [`web/notesView.js`](https://github.com/yujiankoh/modulo/blob/main/web/notesView.js) (Notes and documents), [`server/index.js`](https://github.com/yujiankoh/modulo/blob/main/server/index.js) (Timetable proxy), [`app/app/src/main/java/com/example/modulo/MainActivity.kt`](https://github.com/yujiankoh/modulo/blob/main/app/app/src/main/java/com/example/modulo/MainActivity.kt) (Android app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry"]
  node_web_entry["Web entry<br/>[main.js]"]
  node_web_router["Web routing<br/>[router.js]"]
  node_android_app["Android app<br/>[MainActivity.kt]"]
end

subgraph group_academic["Academic planning"]
  node_timetable["Timetable workflow<br/>[timetable.js]"]
  node_timetable_edit["Timetable editing<br/>[timetableEditor.js]"]
  node_timetable_view["Schedule view<br/>[timetableView.js]"]
  node_parse_proxy["Timetable proxy<br/>[index.js]"]
  node_tasks["Task tracking<br/>[task.js]"]
  node_calendar["Calendar view<br/>[calendarView.js]"]
  node_grades["GPA calculation<br/>[gpa.js]"]
  node_handbooks["Handbooks<br/>[handbooks.js]"]
  node_notes_view["Notes and documents<br/>[notesView.js]"]
  node_notes_logic["Notes rules<br/>[notes.js]"]
end

subgraph group_study["Study productivity"]
  node_study_timer["Study sessions<br/>[studyTimer.js]"]
  node_city_logic["City growth<br/>[growth.js]"]
  node_city_view["City display<br/>[cityView.js]"]
end

subgraph group_storage["Data and sync"]
  node_auth["Google authentication<br/>[auth.js]"]
  node_data["App data and mode<br/>[data.js]"]
  node_drive["Drive sync<br/>[drive.js]"]
  node_migration["Sync conflict rules<br/>[migration.js]"]
end

subgraph group_services["External services"]
  node_google_drive[("Google Drive")]
  node_gemini{{"Gemini Vision API"}}
end

node_student(("Student"))

node_student -->|"uses web app"| node_web_entry
node_student -->|"uses mobile app"| node_android_app
node_web_entry -->|"requests sign-in"| node_auth
node_web_entry -->|"selects storage mode"| node_data
node_web_entry -->|"loads or copies data"| node_drive
node_web_entry -->|"checks conflicts"| node_migration
node_web_entry -->|"starts app"| node_web_router
node_student -->|"uploads timetable"| node_timetable
node_timetable -->|"submits image"| node_parse_proxy
node_parse_proxy -->|"requests parsing"| node_gemini
node_timetable -->|"opens corrections"| node_timetable_edit
node_student -->|"corrects schedule"| node_timetable_edit
node_student -->|"manages tasks"| node_tasks
node_student -->|"views productivity"| node_calendar
node_student -->|"starts session"| node_study_timer
node_study_timer -->|"derives growth"| node_city_logic
node_city_logic -->|"provides city state"| node_city_view
node_student -->|"manages notes"| node_notes_view
node_notes_view -->|"validates and filters"| node_notes_logic
node_notes_view -->|"ensures token"| node_auth
node_notes_view -->|"reads and writes files"| node_drive
node_student -->|"calculates GPA"| node_grades
node_student -->|"manages semesters"| node_handbooks
node_auth -->|"authorizes access"| node_google_drive
node_drive -->|"syncs app data"| node_google_drive
node_notes_view -->|"manages note files"| node_google_drive
node_android_app -.->|"syncs data"| node_google_drive
node_android_app -.->|"requests timetable parsing"| node_parse_proxy
node_parse_proxy -->|"returns parsed schedule"| node_student
node_timetable_edit -->|"shows corrected schedule"| node_timetable_view

click node_web_entry "https://github.com/yujiankoh/modulo/blob/main/web/main.js"
click node_web_router "https://github.com/yujiankoh/modulo/blob/main/web/router.js"
click node_android_app "https://github.com/yujiankoh/modulo/blob/main/app/app/src/main/java/com/example/modulo/MainActivity.kt"
click node_timetable "https://github.com/yujiankoh/modulo/blob/main/web/timetable.js"
click node_timetable_edit "https://github.com/yujiankoh/modulo/blob/main/web/timetableEditor.js"
click node_timetable_view "https://github.com/yujiankoh/modulo/blob/main/web/timetableView.js"
click node_parse_proxy "https://github.com/yujiankoh/modulo/blob/main/server/index.js"
click node_tasks "https://github.com/yujiankoh/modulo/blob/main/web/task.js"
click node_calendar "https://github.com/yujiankoh/modulo/blob/main/web/calendarView.js"
click node_grades "https://github.com/yujiankoh/modulo/blob/main/web/logic/gpa.js"
click node_handbooks "https://github.com/yujiankoh/modulo/blob/main/web/logic/handbooks.js"
click node_study_timer "https://github.com/yujiankoh/modulo/blob/main/web/studyTimer.js"
click node_city_logic "https://github.com/yujiankoh/modulo/blob/main/web/logic/growth.js"
click node_city_view "https://github.com/yujiankoh/modulo/blob/main/web/cityView.js"
click node_notes_view "https://github.com/yujiankoh/modulo/blob/main/web/notesView.js"
click node_notes_logic "https://github.com/yujiankoh/modulo/blob/main/web/logic/notes.js"
click node_auth "https://github.com/yujiankoh/modulo/blob/main/web/auth.js"
click node_data "https://github.com/yujiankoh/modulo/blob/main/web/data.js"
click node_drive "https://github.com/yujiankoh/modulo/blob/main/web/drive.js"
click node_migration "https://github.com/yujiankoh/modulo/blob/main/web/logic/migration.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_web_entry,node_web_router,node_android_app toneBlue
class node_timetable,node_timetable_edit,node_timetable_view,node_parse_proxy,node_tasks,node_calendar,node_grades,node_handbooks,node_notes_view,node_notes_logic toneAmber
class node_study_timer,node_city_logic,node_city_view toneMint
class node_auth,node_data,node_drive,node_migration toneRose
class node_google_drive,node_gemini,node_student toneIndigo
```

## Components

### App entry

- [Web entry](https://github.com/yujiankoh/modulo/blob/main/web/main.js): `web/main.js`
- [Web routing](https://github.com/yujiankoh/modulo/blob/main/web/router.js): `web/router.js`
- [Android app](https://github.com/yujiankoh/modulo/blob/main/app/app/src/main/java/com/example/modulo/MainActivity.kt): `app/app/src/main/java/com/example/modulo/MainActivity.kt`

### Academic planning

- [Timetable workflow](https://github.com/yujiankoh/modulo/blob/main/web/timetable.js): `web/timetable.js`
- [Timetable editing](https://github.com/yujiankoh/modulo/blob/main/web/timetableEditor.js): `web/timetableEditor.js`
- [Schedule view](https://github.com/yujiankoh/modulo/blob/main/web/timetableView.js): `web/timetableView.js`
- [Timetable proxy](https://github.com/yujiankoh/modulo/blob/main/server/index.js): `server/index.js`
- [Task tracking](https://github.com/yujiankoh/modulo/blob/main/web/task.js): `web/task.js`
- [Calendar view](https://github.com/yujiankoh/modulo/blob/main/web/calendarView.js): `web/calendarView.js`
- [GPA calculation](https://github.com/yujiankoh/modulo/blob/main/web/logic/gpa.js): `web/logic/gpa.js`
- [Handbooks](https://github.com/yujiankoh/modulo/blob/main/web/logic/handbooks.js): `web/logic/handbooks.js`
- [Notes and documents](https://github.com/yujiankoh/modulo/blob/main/web/notesView.js): `web/notesView.js`
- [Notes rules](https://github.com/yujiankoh/modulo/blob/main/web/logic/notes.js): `web/logic/notes.js`

### Study productivity

- [Study sessions](https://github.com/yujiankoh/modulo/blob/main/web/studyTimer.js): `web/studyTimer.js`
- [City growth](https://github.com/yujiankoh/modulo/blob/main/web/logic/growth.js): `web/logic/growth.js`
- [City display](https://github.com/yujiankoh/modulo/blob/main/web/cityView.js): `web/cityView.js`

### Data and sync

- [Google authentication](https://github.com/yujiankoh/modulo/blob/main/web/auth.js): `web/auth.js`
- [App data and mode](https://github.com/yujiankoh/modulo/blob/main/web/data.js): `web/data.js`
- [Drive sync](https://github.com/yujiankoh/modulo/blob/main/web/drive.js): `web/drive.js`
- [Sync conflict rules](https://github.com/yujiankoh/modulo/blob/main/web/logic/migration.js): `web/logic/migration.js`

### External services

- **Google Drive**
- **Gemini Vision API**

### Other components

- **Student**

## Connections

- Student → Web entry: uses web app
- Student → Android app: uses mobile app
- Web entry → Google authentication: requests sign-in
- Web entry → App data and mode: selects storage mode
- Web entry → Drive sync: loads or copies data
- Web entry → Sync conflict rules: checks conflicts
- Web entry → Web routing: starts app
- Student → Timetable workflow: uploads timetable
- Timetable workflow → Timetable proxy: submits image
- Timetable proxy → Gemini Vision API: requests parsing
- Timetable workflow → Timetable editing: opens corrections
- Student → Timetable editing: corrects schedule
- Student → Task tracking: manages tasks
- Student → Calendar view: views productivity
- Student → Study sessions: starts session
- Study sessions → City growth: derives growth
- City growth → City display: provides city state
- Student → Notes and documents: manages notes
- Notes and documents → Notes rules: validates and filters
- Notes and documents → Google authentication: ensures token
- Notes and documents → Drive sync: reads and writes files
- Student → GPA calculation: calculates GPA
- Student → Handbooks: manages semesters
- Google authentication → Google Drive: authorizes access
- Drive sync → Google Drive: syncs app data
- Notes and documents → Google Drive: manages note files
- Android app → Google Drive: syncs data
- Android app → Timetable proxy: requests timetable parsing
- Timetable proxy → Student: returns parsed schedule
- Timetable editing → Schedule view: shows corrected schedule