# jbl2023-2879-91296-cpu/karaok architecture

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

- Interactive diagram: https://gitdiagram.com/jbl2023-2879-91296-cpu/karaok
- Repository: https://github.com/jbl2023-2879-91296-cpu/karaok

## Overview

KaraOK is a Flutter client and Flask API for assessing karaoke recordings, presenting saved results, and recommending amplifier adjustments. The principal workflow is record or upload → authenticate when needed → analyze and score five audio features → view reports and save history. Separate branches cover account and profile management, settings recommendations, and the local Admin Console’s policy-controlled data administration. The tree and excerpts support the backend route and service boundaries; frontend internals and several report/storage implementations were not sampled, so their links are limited to documented capabilities.

Main entry points: [`backend/karaok/application.py`](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/application.py) (Flask composition), [`backend/karaok/audio_pipeline/pipeline.py`](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/audio_pipeline/pipeline.py) (Upload pipeline), [`backend/karaok/modules/assessments/routes.py`](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/assessments/routes.py) (Assessment routes), [`backend/karaok/modules/settings_recommendations/routes.py`](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/settings_recommendations/routes.py) (Recommendation routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_flutter["Flutter app"]
end

subgraph group_api["API and assessment"]
  node_flask["Flask composition<br/>[application.py]"]
  node_authroutes["Account routes<br/>[routes.py]"]
  node_accounts["Account services<br/>[accounts.py]"]
  node_audioroutes["Audio routes<br/>[routes.py]"]
  node_pipeline["Upload pipeline<br/>[pipeline.py]"]
  node_execution["Analyzer execution<br/>[execution.py]"]
  node_analyzer["Audio analyzer<br/>[audio_analyzer.py]"]
  node_thresholds["Quality scoring<br/>[scoring.py]"]
end

subgraph group_results["Results and settings"]
  node_assessmentroutes["Assessment routes<br/>[routes.py]"]
  node_assessmentservice["Assessment results<br/>[assessments.py]"]
  node_visuals["Visual reports<br/>[visualizations.py]"]
  node_recommendations["Settings recommendations<br/>[recommendations.py]"]
  node_recommendengine["Recommendation engine<br/>[engine.py]"]
  node_settingsroutes["Recommendation routes<br/>[routes.py]"]
  node_profiles["Saved profiles<br/>[profiles.py]"]
end

subgraph group_admin["Administration"]
  node_webconsole["Admin Console<br/>[index.php]"]
  node_adminclient["Admin API client<br/>[AdminApiClient.php]"]
  node_adminroutes["Data administration API<br/>[routes.py]"]
  node_adminservice["Data administration<br/>[service.py]"]
end

node_person(("KaraOK user"))
node_adminuser(("Console operator"))
node_mysql[("MySQL")]
node_reportdata["Reference recordings"]

node_person -->|"uses"| node_flutter
node_flutter -->|"API requests"| node_flask
node_flask -->|"registers"| node_authroutes
node_flask -->|"registers"| node_audioroutes
node_flask -->|"registers"| node_assessmentroutes
node_flask -->|"registers"| node_settingsroutes
node_authroutes -->|"dispatches"| node_accounts
node_audioroutes -->|"dispatches"| node_pipeline
node_pipeline -->|"runs"| node_execution
node_execution -->|"executes"| node_analyzer
node_pipeline -->|"scores"| node_thresholds
node_pipeline -->|"builds"| node_recommendations
node_recommendations -->|"generates"| node_recommendengine
node_assessmentroutes -->|"dispatches"| node_assessmentservice
node_assessmentroutes -->|"dispatches"| node_visuals
node_settingsroutes -->|"dispatches"| node_profiles
node_settingsroutes -->|"loads"| node_recommendations
node_pipeline -->|"saves assessments"| node_mysql
node_assessmentservice -->|"reads history"| node_mysql
node_visuals -->|"reads report data"| node_mysql
node_thresholds -.->|"uses reference"| node_reportdata
node_adminuser -->|"uses"| node_webconsole
node_webconsole -->|"calls"| node_adminclient
node_adminclient -->|"API requests"| node_adminroutes
node_adminroutes -->|"dispatches"| node_adminservice
node_adminservice -->|"reads and writes"| node_mysql

click node_flutter "https://github.com/jbl2023-2879-91296-cpu/karaok/tree/main/frontend"
click node_webconsole "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/admin/public/index.php"
click node_adminclient "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/admin/app/Api/AdminApiClient.php"
click node_flask "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/application.py"
click node_authroutes "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/auth/routes.py"
click node_accounts "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/auth/accounts.py"
click node_audioroutes "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/audio_analysis/routes.py"
click node_pipeline "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/audio_pipeline/pipeline.py"
click node_execution "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/audio_pipeline/execution.py"
click node_analyzer "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/audio_analyzer.py"
click node_thresholds "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/audio_thresholds/scoring.py"
click node_assessmentroutes "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/assessments/routes.py"
click node_assessmentservice "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/results/assessments.py"
click node_visuals "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/results/visualizations.py"
click node_recommendations "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/audio_pipeline/recommendations.py"
click node_recommendengine "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/settings_recommendations/engine.py"
click node_settingsroutes "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/settings_recommendations/routes.py"
click node_profiles "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/results/profiles.py"
click node_adminroutes "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/admin_data/routes.py"
click node_adminservice "https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/admin/data/service.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_flutter,node_person toneBlue
class node_flask,node_authroutes,node_accounts,node_audioroutes,node_pipeline,node_execution,node_analyzer,node_thresholds,node_mysql toneAmber
class node_assessmentroutes,node_assessmentservice,node_visuals,node_recommendations,node_recommendengine,node_settingsroutes,node_profiles toneMint
class node_webconsole,node_adminclient,node_adminroutes,node_adminservice toneRose
class node_adminuser,node_reportdata toneIndigo
```

## Components

### Client experience

- [Flutter app](https://github.com/jbl2023-2879-91296-cpu/karaok/tree/main/frontend): `frontend`

### API and assessment

- [Flask composition](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/application.py): `backend/karaok/application.py`
- [Account routes](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/auth/routes.py): `backend/karaok/modules/auth/routes.py`
- [Account services](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/auth/accounts.py): `backend/karaok/auth/accounts.py`
- [Audio routes](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/audio_analysis/routes.py): `backend/karaok/modules/audio_analysis/routes.py`
- [Upload pipeline](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/audio_pipeline/pipeline.py): `backend/karaok/audio_pipeline/pipeline.py`
- [Analyzer execution](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/audio_pipeline/execution.py): `backend/karaok/audio_pipeline/execution.py`
- [Audio analyzer](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/audio_analyzer.py): `backend/audio_analyzer.py`
- [Quality scoring](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/audio_thresholds/scoring.py): `backend/audio_thresholds/scoring.py`

### Results and settings

- [Assessment routes](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/assessments/routes.py): `backend/karaok/modules/assessments/routes.py`
- [Assessment results](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/results/assessments.py): `backend/karaok/results/assessments.py`
- [Visual reports](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/results/visualizations.py): `backend/karaok/results/visualizations.py`
- [Settings recommendations](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/audio_pipeline/recommendations.py): `backend/karaok/audio_pipeline/recommendations.py`
- [Recommendation engine](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/settings_recommendations/engine.py): `backend/settings_recommendations/engine.py`
- [Recommendation routes](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/settings_recommendations/routes.py): `backend/karaok/modules/settings_recommendations/routes.py`
- [Saved profiles](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/results/profiles.py): `backend/karaok/results/profiles.py`

### Administration

- [Admin Console](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/admin/public/index.php): `admin/public/index.php`
- [Admin API client](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/admin/app/Api/AdminApiClient.php): `admin/app/Api/AdminApiClient.php`
- [Data administration API](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/modules/admin_data/routes.py): `backend/karaok/modules/admin_data/routes.py`
- [Data administration](https://github.com/jbl2023-2879-91296-cpu/karaok/blob/main/backend/karaok/admin/data/service.py): `backend/karaok/admin/data/service.py`

### Other components

- **KaraOK user**
- **Console operator**
- **MySQL**
- **Reference recordings**

## Connections

- KaraOK user → Flutter app: uses
- Flutter app → Flask composition: API requests
- Flask composition → Account routes: registers
- Flask composition → Audio routes: registers
- Flask composition → Assessment routes: registers
- Flask composition → Recommendation routes: registers
- Account routes → Account services: dispatches
- Audio routes → Upload pipeline: dispatches
- Upload pipeline → Analyzer execution: runs
- Analyzer execution → Audio analyzer: executes
- Upload pipeline → Quality scoring: scores
- Upload pipeline → Settings recommendations: builds
- Settings recommendations → Recommendation engine: generates
- Assessment routes → Assessment results: dispatches
- Assessment routes → Visual reports: dispatches
- Recommendation routes → Saved profiles: dispatches
- Recommendation routes → Settings recommendations: loads
- Upload pipeline → MySQL: saves assessments
- Assessment results → MySQL: reads history
- Visual reports → MySQL: reads report data
- Quality scoring → Reference recordings: uses reference
- Console operator → Admin Console: uses
- Admin Console → Admin API client: calls
- Admin API client → Data administration API: API requests
- Data administration API → Data administration: dispatches
- Data administration → MySQL: reads and writes