# goldenmelky/betterviva architecture

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

- Interactive diagram: https://gitdiagram.com/goldenmelky/betterviva
- Repository: https://github.com/goldenmelky/betterviva

## Overview

BetterViva is a mobile-first ClasseViva client: students sign in, then view unified homework and agenda, timetable, grades, absences and noticeboard content. The browser keeps account-scoped data for quick and offline access; the backend holds short-lived sessions and persisted timetable preferences. The README also documents notifications, settings, feedback and PWA asset caching. The graph preserves these product branches, but sampled backend excerpts do not expose enough route code to trace every API call; several relationships are therefore omitted rather than inferred.

Main entry points: [`main.py`](https://github.com/goldenmelky/betterviva/blob/main/main.py) (HTTP API), [`static/app.js`](https://github.com/goldenmelky/betterviva/blob/main/static/app.js) (App shell), [`static/noticeboard.js`](https://github.com/goldenmelky/betterviva/blob/main/static/noticeboard.js) (Noticeboard view), [`static/settings.js`](https://github.com/goldenmelky/betterviva/blob/main/static/settings.js) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Student app"]
  node_app["App shell<br/>[app.js]"]
  node_setup["Setup editor<br/>[setup.js]"]
  node_home["Home events<br/>[home.js]"]
  node_calendar["Calendar<br/>[calendar.js]"]
  node_grades_ui["Grades view<br/>[grades.js]"]
  node_absences_ui["Absences view<br/>[absences.js]"]
  node_noticeboard["Noticeboard view<br/>[noticeboard.js]"]
  node_notifications["Notifications<br/>[notifications.js]"]
  node_settings["Settings<br/>[settings.js]"]
  node_subjects["Subject preferences<br/>[subjects.js]"]
  node_sheet["Content sheets<br/>[sheet.js]"]
  node_pwa["PWA support<br/>[pwa.js]"]
  node_service_worker["Asset cache<br/>[sw.js]"]
end

subgraph group_server["Backend services"]
  node_api["HTTP API<br/>[main.py]"]
  node_feedback["Feedback forwarding<br/>[main.py]"]
  node_classeviva["ClasseViva client<br/>[classeviva.py]"]
end

subgraph group_domain["Academic data"]
  node_event_builder["Event unification<br/>[events.py]"]
  node_test_classifier["Test detection<br/>[verifiche.py]"]
  node_event_overrides["Event corrections<br/>[overrides.py]"]
  node_grade_stats["Grade statistics<br/>[grades.py]"]
  node_timetable_logic["Timetable proposal<br/>[timetable.py]"]
end

subgraph group_state["Persistence"]
  node_database[("SQLite preferences<br/>[db.py]")]
  node_browser_cache[("Offline account cache<br/>[app.js]")]
end

node_student(("Student"))
node_classeviva_service["ClasseViva service"]
node_telegram["Telegram bot"]

node_student -->|"uses"| node_app
node_app -->|"caches data"| node_browser_cache
node_app -.->|"requests data"| node_api
node_event_builder -->|"classifies text"| node_test_classifier
node_student -->|"configures timetable"| node_setup
node_student -->|"views events"| node_home
node_student -->|"views calendar"| node_calendar
node_student -->|"views grades"| node_grades_ui
node_student -->|"views absences"| node_absences_ui
node_student -->|"views notices"| node_noticeboard
node_student -->|"checks updates"| node_notifications
node_student -->|"changes settings"| node_settings
node_settings -.->|"edits subjects"| node_subjects
node_noticeboard -.->|"opens content"| node_sheet
node_app -.->|"enables install"| node_pwa
node_pwa -.->|"registers worker"| node_service_worker
node_api -->|"authenticates user"| node_classeviva
node_classeviva -.->|"requests school data"| node_classeviva_service
node_api -->|"accepts feedback"| node_feedback
node_feedback -->|"forwards message"| node_telegram
node_api -.->|"stores preferences"| node_database
node_api -.->|"builds unified events"| node_event_builder
node_api -.->|"computes averages"| node_grade_stats
node_api -.->|"proposes timetable"| node_timetable_logic
node_api -.->|"applies corrections"| node_event_overrides

click node_app "https://github.com/goldenmelky/betterviva/blob/main/static/app.js"
click node_setup "https://github.com/goldenmelky/betterviva/blob/main/static/setup.js"
click node_home "https://github.com/goldenmelky/betterviva/blob/main/static/home.js"
click node_calendar "https://github.com/goldenmelky/betterviva/blob/main/static/calendar.js"
click node_grades_ui "https://github.com/goldenmelky/betterviva/blob/main/static/grades.js"
click node_absences_ui "https://github.com/goldenmelky/betterviva/blob/main/static/absences.js"
click node_noticeboard "https://github.com/goldenmelky/betterviva/blob/main/static/noticeboard.js"
click node_notifications "https://github.com/goldenmelky/betterviva/blob/main/static/notifications.js"
click node_settings "https://github.com/goldenmelky/betterviva/blob/main/static/settings.js"
click node_subjects "https://github.com/goldenmelky/betterviva/blob/main/static/subjects.js"
click node_sheet "https://github.com/goldenmelky/betterviva/blob/main/static/sheet.js"
click node_pwa "https://github.com/goldenmelky/betterviva/blob/main/static/pwa.js"
click node_service_worker "https://github.com/goldenmelky/betterviva/blob/main/static/sw.js"
click node_api "https://github.com/goldenmelky/betterviva/blob/main/main.py"
click node_feedback "https://github.com/goldenmelky/betterviva/blob/main/main.py"
click node_classeviva "https://github.com/goldenmelky/betterviva/blob/main/classeviva.py"
click node_event_builder "https://github.com/goldenmelky/betterviva/blob/main/events.py"
click node_test_classifier "https://github.com/goldenmelky/betterviva/blob/main/verifiche.py"
click node_event_overrides "https://github.com/goldenmelky/betterviva/blob/main/overrides.py"
click node_grade_stats "https://github.com/goldenmelky/betterviva/blob/main/grades.py"
click node_timetable_logic "https://github.com/goldenmelky/betterviva/blob/main/timetable.py"
click node_database "https://github.com/goldenmelky/betterviva/blob/main/db.py"
click node_browser_cache "https://github.com/goldenmelky/betterviva/blob/main/static/app.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_app,node_setup,node_home,node_calendar,node_grades_ui,node_absences_ui,node_noticeboard,node_notifications,node_settings,node_subjects,node_sheet,node_pwa,node_service_worker toneBlue
class node_api,node_feedback,node_classeviva toneAmber
class node_event_builder,node_test_classifier,node_event_overrides,node_grade_stats,node_timetable_logic toneMint
class node_database,node_browser_cache toneRose
class node_student,node_classeviva_service,node_telegram toneIndigo
```

## Components

### Student app

- [App shell](https://github.com/goldenmelky/betterviva/blob/main/static/app.js): `static/app.js`
- [Setup editor](https://github.com/goldenmelky/betterviva/blob/main/static/setup.js): `static/setup.js`
- [Home events](https://github.com/goldenmelky/betterviva/blob/main/static/home.js): `static/home.js`
- [Calendar](https://github.com/goldenmelky/betterviva/blob/main/static/calendar.js): `static/calendar.js`
- [Grades view](https://github.com/goldenmelky/betterviva/blob/main/static/grades.js): `static/grades.js`
- [Absences view](https://github.com/goldenmelky/betterviva/blob/main/static/absences.js): `static/absences.js`
- [Noticeboard view](https://github.com/goldenmelky/betterviva/blob/main/static/noticeboard.js): `static/noticeboard.js`
- [Notifications](https://github.com/goldenmelky/betterviva/blob/main/static/notifications.js): `static/notifications.js`
- [Settings](https://github.com/goldenmelky/betterviva/blob/main/static/settings.js): `static/settings.js`
- [Subject preferences](https://github.com/goldenmelky/betterviva/blob/main/static/subjects.js): `static/subjects.js`
- [Content sheets](https://github.com/goldenmelky/betterviva/blob/main/static/sheet.js): `static/sheet.js`
- [PWA support](https://github.com/goldenmelky/betterviva/blob/main/static/pwa.js): `static/pwa.js`
- [Asset cache](https://github.com/goldenmelky/betterviva/blob/main/static/sw.js): `static/sw.js`

### Backend services

- [HTTP API](https://github.com/goldenmelky/betterviva/blob/main/main.py): `main.py`
- [Feedback forwarding](https://github.com/goldenmelky/betterviva/blob/main/main.py): `main.py`
- [ClasseViva client](https://github.com/goldenmelky/betterviva/blob/main/classeviva.py): `classeviva.py`

### Academic data

- [Event unification](https://github.com/goldenmelky/betterviva/blob/main/events.py): `events.py`
- [Test detection](https://github.com/goldenmelky/betterviva/blob/main/verifiche.py): `verifiche.py`
- [Event corrections](https://github.com/goldenmelky/betterviva/blob/main/overrides.py): `overrides.py`
- [Grade statistics](https://github.com/goldenmelky/betterviva/blob/main/grades.py): `grades.py`
- [Timetable proposal](https://github.com/goldenmelky/betterviva/blob/main/timetable.py): `timetable.py`

### Persistence

- [SQLite preferences](https://github.com/goldenmelky/betterviva/blob/main/db.py): `db.py`
- [Offline account cache](https://github.com/goldenmelky/betterviva/blob/main/static/app.js): `static/app.js`

### Other components

- **Student**
- **ClasseViva service**
- **Telegram bot**

## Connections

- Student → App shell: uses (evidence: `README.md`)
- App shell → Offline account cache: caches data (evidence: `static/app.js`)
- App shell → HTTP API: requests data
- Event unification → Test detection: classifies text (evidence: `events.py`)
- Student → Setup editor: configures timetable (evidence: `README.md`)
- Student → Home events: views events (evidence: `README.md`)
- Student → Calendar: views calendar (evidence: `README.md`)
- Student → Grades view: views grades (evidence: `README.md`)
- Student → Absences view: views absences (evidence: `README.md`)
- Student → Noticeboard view: views notices (evidence: `README.md`)
- Student → Notifications: checks updates (evidence: `README.md`)
- Student → Settings: changes settings (evidence: `README.md`)
- Settings → Subject preferences: edits subjects
- Noticeboard view → Content sheets: opens content
- App shell → PWA support: enables install
- PWA support → Asset cache: registers worker
- HTTP API → ClasseViva client: authenticates user (evidence: `main.py`)
- ClasseViva client → ClasseViva service: requests school data
- HTTP API → Feedback forwarding: accepts feedback (evidence: `README.md`)
- Feedback forwarding → Telegram bot: forwards message (evidence: `README.md`)
- HTTP API → SQLite preferences: stores preferences (evidence: `main.py`)
- HTTP API → Event unification: builds unified events (evidence: `main.py`)
- HTTP API → Grade statistics: computes averages (evidence: `main.py`)
- HTTP API → Timetable proposal: proposes timetable (evidence: `main.py`)
- HTTP API → Event corrections: applies corrections (evidence: `main.py`)