# shweta-nair/orator architecture

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

- Interactive diagram: https://gitdiagram.com/shweta-nair/orator
- Repository: https://github.com/shweta-nair/orator

## Overview

Orator is a Flask and vanilla-JavaScript presentation rehearsal coach. A presenter creates a scripted presentation, rehearses while the browser records video and transcribes speech, then submits the attempt for speech and visual analysis, score fusion, and a saved report. Dashboard, history, and progress aggregate saved attempts. The repository also contains a separate dataset-collection and PyTorch research scaffold; the README says trained models are not used by the app. Research links below describe documented capabilities, not inspected end-to-end wiring.

Main entry points: [`frontend/js/api.js`](https://github.com/shweta-nair/orator/blob/main/frontend/js/api.js) (API client), [`app/routes/attempts.py`](https://github.com/shweta-nair/orator/blob/main/app/routes/attempts.py) (Attempt routes), [`frontend/js/app.js`](https://github.com/shweta-nair/orator/blob/main/frontend/js/app.js) (App shell), [`app/models.py`](https://github.com/shweta-nair/orator/blob/main/app/models.py) (Domain models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Rehearsal UI"]
  node_ui_shell["App shell<br/>[app.js]"]
  node_ui_auth["Auth views<br/>[auth.js]"]
  node_ui_api["API client<br/>[api.js]"]
  node_ui_presentation["Presentation flow<br/>[presentation.js]"]
  node_ui_recorder["Recorder<br/>[recorder.js]"]
  node_ui_teleprompter["Teleprompter<br/>[teleprompter.js]"]
  node_ui_report["Report view<br/>[report.js]"]
  node_ui_dashboard["Dashboard view<br/>[dashboard.js]"]
  node_ui_progress["Progress view<br/>[progress.js]"]
end

subgraph group_api["Application API"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_presentation_routes["Presentation routes<br/>[presentations.py]"]
  node_attempt_routes["Attempt routes<br/>[attempts.py]"]
  node_stats_routes["Stats routes<br/>[stats.py]"]
  node_auth_guard["Session auth<br/>[auth_utils.py]"]
end

subgraph group_analysis["Attempt Analysis"]
  node_speech["Speech metrics<br/>[speech_service.py]"]
  node_vision["Video metrics<br/>[vision_service.py]"]
  node_fusion["Score and feedback<br/>[fusion_service.py]"]
  node_stats["Stats aggregation<br/>[stats_service.py]"]
end

subgraph group_storage["Account and History"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("SQL database<br/>[models.py]")]
end

subgraph group_research["Model Research"]
  node_collection["Dataset collection<br/>[ingest.py]"]
  node_training_data["Training dataset<br/>[dataset.py]"]
  node_train_loop["Experiment runner<br/>[train_common.py]"]
  node_model["Multimodal models"]
end

node_presenter(("Presenter"))
node_browser(("Browser"))
node_webspeech{{"Web Speech API"}}

node_presenter -->|"uses"| node_ui_shell
node_ui_shell -->|"routes to"| node_ui_presentation
node_ui_shell -->|"routes to"| node_ui_report
node_ui_shell -->|"routes to"| node_ui_dashboard
node_ui_shell -->|"routes to"| node_ui_progress
node_ui_auth -->|"requests"| node_ui_api
node_ui_presentation -->|"requests"| node_ui_api
node_ui_report -->|"requests"| node_ui_api
node_ui_dashboard -->|"requests"| node_ui_api
node_ui_progress -->|"requests"| node_ui_api
node_ui_presentation -->|"records"| node_ui_recorder
node_ui_presentation -->|"presents script"| node_ui_teleprompter
node_ui_recorder -->|"captures media"| node_browser
node_browser -.->|"transcribes"| node_webspeech
node_ui_api -->|"calls"| node_auth_routes
node_ui_api -->|"calls"| node_presentation_routes
node_ui_api -->|"submits attempt"| node_attempt_routes
node_ui_api -->|"requests stats"| node_stats_routes
node_auth_routes -->|"reads/writes"| node_models
node_presentation_routes -->|"manages"| node_models
node_attempt_routes -->|"checks session"| node_auth_guard
node_presentation_routes -->|"checks session"| node_auth_guard
node_stats_routes -->|"checks session"| node_auth_guard
node_attempt_routes -->|"analyzes transcript"| node_speech
node_attempt_routes -->|"analyzes video"| node_vision
node_attempt_routes -->|"fuses metrics"| node_fusion
node_attempt_routes -->|"saves attempt"| node_models
node_stats_routes -->|"reads attempts"| node_models
node_stats_routes -->|"aggregates"| node_stats
node_models -->|"persists"| node_database
node_collection -.->|"provides dataset inputs"| node_training_data
node_train_loop -->|"loads data"| node_training_data
node_train_loop -->|"trains"| node_model

click node_ui_shell "https://github.com/shweta-nair/orator/blob/main/frontend/js/app.js"
click node_ui_auth "https://github.com/shweta-nair/orator/blob/main/frontend/js/auth.js"
click node_ui_api "https://github.com/shweta-nair/orator/blob/main/frontend/js/api.js"
click node_ui_presentation "https://github.com/shweta-nair/orator/blob/main/frontend/js/presentation.js"
click node_ui_recorder "https://github.com/shweta-nair/orator/blob/main/frontend/js/recorder.js"
click node_ui_teleprompter "https://github.com/shweta-nair/orator/blob/main/frontend/js/teleprompter.js"
click node_ui_report "https://github.com/shweta-nair/orator/blob/main/frontend/js/report.js"
click node_ui_dashboard "https://github.com/shweta-nair/orator/blob/main/frontend/js/dashboard.js"
click node_ui_progress "https://github.com/shweta-nair/orator/blob/main/frontend/js/progress.js"
click node_auth_routes "https://github.com/shweta-nair/orator/blob/main/app/routes/auth.py"
click node_presentation_routes "https://github.com/shweta-nair/orator/blob/main/app/routes/presentations.py"
click node_attempt_routes "https://github.com/shweta-nair/orator/blob/main/app/routes/attempts.py"
click node_stats_routes "https://github.com/shweta-nair/orator/blob/main/app/routes/stats.py"
click node_auth_guard "https://github.com/shweta-nair/orator/blob/main/app/auth_utils.py"
click node_models "https://github.com/shweta-nair/orator/blob/main/app/models.py"
click node_database "https://github.com/shweta-nair/orator/blob/main/app/models.py"
click node_speech "https://github.com/shweta-nair/orator/blob/main/app/services/speech_service.py"
click node_vision "https://github.com/shweta-nair/orator/blob/main/app/services/vision_service.py"
click node_fusion "https://github.com/shweta-nair/orator/blob/main/app/services/fusion_service.py"
click node_stats "https://github.com/shweta-nair/orator/blob/main/app/services/stats_service.py"
click node_collection "https://github.com/shweta-nair/orator/blob/main/dataset_collection/scripts/ingest.py"
click node_training_data "https://github.com/shweta-nair/orator/blob/main/training/data/dataset.py"
click node_train_loop "https://github.com/shweta-nair/orator/blob/main/training/train_common.py"
click node_model "https://github.com/shweta-nair/orator/blob/main/training/models/multimodal_model.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_ui_shell,node_ui_auth,node_ui_api,node_ui_presentation,node_ui_recorder,node_ui_teleprompter,node_ui_report,node_ui_dashboard,node_ui_progress,node_browser toneBlue
class node_auth_routes,node_presentation_routes,node_attempt_routes,node_stats_routes,node_auth_guard toneAmber
class node_speech,node_vision,node_fusion,node_stats,node_webspeech toneMint
class node_models,node_database toneRose
class node_collection,node_training_data,node_train_loop,node_model,node_presenter toneIndigo
```

## Components

### Rehearsal UI

- [App shell](https://github.com/shweta-nair/orator/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [Auth views](https://github.com/shweta-nair/orator/blob/main/frontend/js/auth.js): `frontend/js/auth.js`
- [API client](https://github.com/shweta-nair/orator/blob/main/frontend/js/api.js): `frontend/js/api.js`
- [Presentation flow](https://github.com/shweta-nair/orator/blob/main/frontend/js/presentation.js): `frontend/js/presentation.js`
- [Recorder](https://github.com/shweta-nair/orator/blob/main/frontend/js/recorder.js): `frontend/js/recorder.js`
- [Teleprompter](https://github.com/shweta-nair/orator/blob/main/frontend/js/teleprompter.js): `frontend/js/teleprompter.js`
- [Report view](https://github.com/shweta-nair/orator/blob/main/frontend/js/report.js): `frontend/js/report.js`
- [Dashboard view](https://github.com/shweta-nair/orator/blob/main/frontend/js/dashboard.js): `frontend/js/dashboard.js`
- [Progress view](https://github.com/shweta-nair/orator/blob/main/frontend/js/progress.js): `frontend/js/progress.js`

### Application API

- [Auth routes](https://github.com/shweta-nair/orator/blob/main/app/routes/auth.py): `app/routes/auth.py`
- [Presentation routes](https://github.com/shweta-nair/orator/blob/main/app/routes/presentations.py): `app/routes/presentations.py`
- [Attempt routes](https://github.com/shweta-nair/orator/blob/main/app/routes/attempts.py): `app/routes/attempts.py`
- [Stats routes](https://github.com/shweta-nair/orator/blob/main/app/routes/stats.py): `app/routes/stats.py`
- [Session auth](https://github.com/shweta-nair/orator/blob/main/app/auth_utils.py): `app/auth_utils.py`

### Attempt Analysis

- [Speech metrics](https://github.com/shweta-nair/orator/blob/main/app/services/speech_service.py): `app/services/speech_service.py`
- [Video metrics](https://github.com/shweta-nair/orator/blob/main/app/services/vision_service.py): `app/services/vision_service.py`
- [Score and feedback](https://github.com/shweta-nair/orator/blob/main/app/services/fusion_service.py): `app/services/fusion_service.py`
- [Stats aggregation](https://github.com/shweta-nair/orator/blob/main/app/services/stats_service.py): `app/services/stats_service.py`

### Account and History

- [Domain models](https://github.com/shweta-nair/orator/blob/main/app/models.py): `app/models.py`
- [SQL database](https://github.com/shweta-nair/orator/blob/main/app/models.py): `app/models.py`

### Model Research

- [Dataset collection](https://github.com/shweta-nair/orator/blob/main/dataset_collection/scripts/ingest.py): `dataset_collection/scripts/ingest.py`
- [Training dataset](https://github.com/shweta-nair/orator/blob/main/training/data/dataset.py): `training/data/dataset.py`
- [Experiment runner](https://github.com/shweta-nair/orator/blob/main/training/train_common.py): `training/train_common.py`
- [Multimodal models](https://github.com/shweta-nair/orator/blob/main/training/models/multimodal_model.py): `training/models/multimodal_model.py`

### Other components

- **Presenter**
- **Browser**
- **Web Speech API**

## Connections

- Presenter → App shell: uses
- App shell → Presentation flow: routes to
- App shell → Report view: routes to
- App shell → Dashboard view: routes to
- App shell → Progress view: routes to
- Auth views → API client: requests
- Presentation flow → API client: requests
- Report view → API client: requests
- Dashboard view → API client: requests
- Progress view → API client: requests
- Presentation flow → Recorder: records
- Presentation flow → Teleprompter: presents script
- Recorder → Browser: captures media
- Browser → Web Speech API: transcribes
- API client → Auth routes: calls
- API client → Presentation routes: calls
- API client → Attempt routes: submits attempt
- API client → Stats routes: requests stats
- Auth routes → Domain models: reads/writes
- Presentation routes → Domain models: manages
- Attempt routes → Session auth: checks session
- Presentation routes → Session auth: checks session
- Stats routes → Session auth: checks session
- Attempt routes → Speech metrics: analyzes transcript
- Attempt routes → Video metrics: analyzes video
- Attempt routes → Score and feedback: fuses metrics
- Attempt routes → Domain models: saves attempt
- Stats routes → Domain models: reads attempts
- Stats routes → Stats aggregation: aggregates
- Domain models → SQL database: persists
- Dataset collection → Training dataset: provides dataset inputs
- Experiment runner → Training dataset: loads data
- Experiment runner → Multimodal models: trains