# shiroshoes/novasight architecture

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

- Interactive diagram: https://gitdiagram.com/shiroshoes/novasight
- Repository: https://github.com/shiroshoes/novasight

## Overview

NovaSight is a Flask-based academic analytics application for managing grade-sheet uploads, validating and preparing student data, and serving role-specific dashboards and forecasts. The main workflow runs from an administrator’s upload through preprocessing and catalog checks into persisted datasets; training and analytics then use those datasets to support historical and predictive views. The tree and excerpts support the main data-access and dashboard links, but do not expose every route implementation, so uncertain internal wiring is omitted.

Main entry points: [`util/db_io.py`](https://github.com/shiroshoes/novasight/blob/main/util/db_io.py) (Dataset data access), [`app/app.py`](https://github.com/shiroshoes/novasight/blob/main/app/app.py) (Flask application), [`preprocessing/preprocess.py`](https://github.com/shiroshoes/novasight/blob/main/preprocessing/preprocess.py) (Workbook preprocessing), [`app/static/js/fileupload.js`](https://github.com/shiroshoes/novasight/blob/main/app/static/js/fileupload.js) (Upload interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Application access"]
  node_app["Flask application<br/>[app.py]"]
  node_admin["Admin routes<br/>[admin.py]"]
  node_college_routes["College routes"]
  node_user_models["User models<br/>[models.py]"]
end

subgraph group_ingest["Dataset ingestion"]
  node_upload_ui["Upload interface<br/>[fileupload.js]"]
  node_upload_api["Upload API<br/>[upload_rotues.py]"]
  node_preprocess["Workbook preprocessing<br/>[preprocess.py]"]
  node_catalog["Catalog validation"]
  node_warning_rules["Warning rules<br/>[warnings_core.py]"]
end

subgraph group_analytics["Analytics and prediction"]
  node_training["Model training<br/>[auto_train.py]"]
  node_dashboard_api["Historical dashboard API<br/>[maindash_routes.py]"]
  node_analysis["Analytics endpoints<br/>[ml_analysis.py]"]
  node_prediction_api["Prediction API<br/>[prediction_api.py]"]
  node_main_ui["Historical dashboard UI<br/>[maindash.js]"]
  node_dean_ui["Dean dashboard UI<br/>[deandash.js]"]
  node_prediction_ui["Prediction dashboard UI<br/>[prediction-dash.js]"]
end

subgraph group_persistence["Persistence"]
  node_data_access["Dataset data access<br/>[db_io.py]"]
  node_sql_store[("MySQL database")]
end

node_staff(("Academic staff"))

node_staff -->|"uses"| node_app
node_app -->|"registers routes"| node_admin
node_app -->|"registers routes"| node_college_routes
node_app -->|"authenticates users"| node_user_models
node_staff -->|"submits workbook"| node_upload_ui
node_upload_ui -->|"sends upload"| node_upload_api
node_upload_api -->|"processes workbook"| node_preprocess
node_preprocess -->|"checks catalog"| node_catalog
node_preprocess -->|"records warnings"| node_warning_rules
node_preprocess -->|"stores datasets"| node_data_access
node_data_access -->|"reads and writes"| node_sql_store
node_training -->|"loads and records"| node_data_access
node_staff -->|"views history"| node_main_ui
node_main_ui -->|"requests dashboard data"| node_dashboard_api
node_dashboard_api -->|"loads datasets"| node_data_access
node_staff -->|"views college analytics"| node_dean_ui
node_dean_ui -->|"requests analytics"| node_analysis
node_analysis -->|"loads model datasets"| node_data_access
node_staff -->|"views forecasts"| node_prediction_ui
node_prediction_ui -->|"requests predictions"| node_prediction_api
node_prediction_api -->|"accesses stored data"| node_data_access

click node_app "https://github.com/shiroshoes/novasight/blob/main/app/app.py"
click node_admin "https://github.com/shiroshoes/novasight/blob/main/routes/admin.py"
click node_college_routes "https://github.com/shiroshoes/novasight/tree/main/routes"
click node_user_models "https://github.com/shiroshoes/novasight/blob/main/database/models.py"
click node_upload_ui "https://github.com/shiroshoes/novasight/blob/main/app/static/js/fileupload.js"
click node_upload_api "https://github.com/shiroshoes/novasight/blob/main/ml_route/upload_rotues.py"
click node_preprocess "https://github.com/shiroshoes/novasight/blob/main/preprocessing/preprocess.py"
click node_catalog "https://github.com/shiroshoes/novasight/blob/main/preprocessing/course_catalog_checker.py"
click node_warning_rules "https://github.com/shiroshoes/novasight/blob/main/preprocessing/warnings_core.py"
click node_training "https://github.com/shiroshoes/novasight/blob/main/training/auto_train.py"
click node_dashboard_api "https://github.com/shiroshoes/novasight/blob/main/ml_route/maindash_routes.py"
click node_analysis "https://github.com/shiroshoes/novasight/blob/main/ml_route/ml_analysis.py"
click node_prediction_api "https://github.com/shiroshoes/novasight/blob/main/ml_route/prediction_api.py"
click node_main_ui "https://github.com/shiroshoes/novasight/blob/main/app/static/js/maindash.js"
click node_dean_ui "https://github.com/shiroshoes/novasight/blob/main/app/static/js/deandash.js"
click node_prediction_ui "https://github.com/shiroshoes/novasight/blob/main/app/static/js/prediction-dash.js"
click node_data_access "https://github.com/shiroshoes/novasight/blob/main/util/db_io.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_app,node_admin,node_college_routes,node_user_models toneBlue
class node_upload_ui,node_upload_api,node_preprocess,node_catalog,node_warning_rules toneAmber
class node_training,node_dashboard_api,node_analysis,node_prediction_api,node_main_ui,node_dean_ui,node_prediction_ui toneMint
class node_data_access,node_sql_store toneRose
class node_staff toneIndigo
```

## Components

### Application access

- [Flask application](https://github.com/shiroshoes/novasight/blob/main/app/app.py): `app/app.py`
- [Admin routes](https://github.com/shiroshoes/novasight/blob/main/routes/admin.py): `routes/admin.py`
- [College routes](https://github.com/shiroshoes/novasight/tree/main/routes): `routes`
- [User models](https://github.com/shiroshoes/novasight/blob/main/database/models.py): `database/models.py`

### Dataset ingestion

- [Upload interface](https://github.com/shiroshoes/novasight/blob/main/app/static/js/fileupload.js): `app/static/js/fileupload.js`
- [Upload API](https://github.com/shiroshoes/novasight/blob/main/ml_route/upload_rotues.py): `ml_route/upload_rotues.py`
- [Workbook preprocessing](https://github.com/shiroshoes/novasight/blob/main/preprocessing/preprocess.py): `preprocessing/preprocess.py`
- [Catalog validation](https://github.com/shiroshoes/novasight/blob/main/preprocessing/course_catalog_checker.py): `preprocessing/course_catalog_checker.py`
- [Warning rules](https://github.com/shiroshoes/novasight/blob/main/preprocessing/warnings_core.py): `preprocessing/warnings_core.py`

### Analytics and prediction

- [Model training](https://github.com/shiroshoes/novasight/blob/main/training/auto_train.py): `training/auto_train.py`
- [Historical dashboard API](https://github.com/shiroshoes/novasight/blob/main/ml_route/maindash_routes.py): `ml_route/maindash_routes.py`
- [Analytics endpoints](https://github.com/shiroshoes/novasight/blob/main/ml_route/ml_analysis.py): `ml_route/ml_analysis.py`
- [Prediction API](https://github.com/shiroshoes/novasight/blob/main/ml_route/prediction_api.py): `ml_route/prediction_api.py`
- [Historical dashboard UI](https://github.com/shiroshoes/novasight/blob/main/app/static/js/maindash.js): `app/static/js/maindash.js`
- [Dean dashboard UI](https://github.com/shiroshoes/novasight/blob/main/app/static/js/deandash.js): `app/static/js/deandash.js`
- [Prediction dashboard UI](https://github.com/shiroshoes/novasight/blob/main/app/static/js/prediction-dash.js): `app/static/js/prediction-dash.js`

### Persistence

- [Dataset data access](https://github.com/shiroshoes/novasight/blob/main/util/db_io.py): `util/db_io.py`
- **MySQL database**

### Other components

- **Academic staff**

## Connections

- Academic staff → Flask application: uses
- Flask application → Admin routes: registers routes
- Flask application → College routes: registers routes
- Flask application → User models: authenticates users
- Academic staff → Upload interface: submits workbook
- Upload interface → Upload API: sends upload
- Upload API → Workbook preprocessing: processes workbook
- Workbook preprocessing → Catalog validation: checks catalog
- Workbook preprocessing → Warning rules: records warnings
- Workbook preprocessing → Dataset data access: stores datasets
- Dataset data access → MySQL database: reads and writes
- Model training → Dataset data access: loads and records
- Academic staff → Historical dashboard UI: views history
- Historical dashboard UI → Historical dashboard API: requests dashboard data
- Historical dashboard API → Dataset data access: loads datasets
- Academic staff → Dean dashboard UI: views college analytics
- Dean dashboard UI → Analytics endpoints: requests analytics
- Analytics endpoints → Dataset data access: loads model datasets
- Academic staff → Prediction dashboard UI: views forecasts
- Prediction dashboard UI → Prediction API: requests predictions
- Prediction API → Dataset data access: accesses stored data