# utkarsh-wadalkar/audora architecture

> Architecture diagram of the GitHub repository utkarsh-wadalkar/audora, 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/utkarsh-wadalkar/audora
- Repository: https://github.com/utkarsh-wadalkar/audora

## Overview

Audora is an Electron desktop app for setting up an Apple Music download environment, submitting track, album, or playlist URLs, and saving lossless downloads as playable FLAC files. Its main workflow runs from the desktop UI through the backend queue and downloader, with Docker-hosted wrapper services supporting authentication and audio retrieval; tracks are converted and organized in the local library. The README also describes playback, history, settings, logs, and a separate marketing site. Some backend routing and marketing-page wiring is unsampled, so those links are limited to documented or directly evidenced relationships.

Main entry points: [`backend/app.py`](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/app.py) (API and events), [`frontend/src/App.tsx`](https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/src/App.tsx) (App shell), [`backend/queue_processor.py`](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/queue_processor.py) (Download queue), [`marketing/app/page.tsx`](https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/app/page.tsx) (Marketing pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_app["App shell<br/>[App.tsx]"]
  node_pages["App pages"]
  node_store["App state<br/>[useAppStore.ts]"]
  node_api["API client<br/>[client.ts]"]
  node_websocket["Live events<br/>[useWebSocket.ts]"]
  node_electron["Electron host<br/>[main.js]"]
  node_process["Backend process"]
end

subgraph group_backend["Backend workflow"]
  node_server["API and events<br/>[app.py]"]
  node_setup["First-run setup<br/>[setup_manager.py]"]
  node_docker["Docker control<br/>[docker_manager.py]"]
  node_auth["Music authentication<br/>[auth_manager.py]"]
  node_wrapper["Wrapper service<br/>[wrapper_manager.py]"]
  node_queue["Download queue<br/>[queue_processor.py]"]
  node_downloader["Track retrieval"]
end

subgraph group_local["Local music"]
  node_converter["FLAC conversion<br/>[flac_converter.py]"]
  node_library["Library and playback<br/>[library_manager.py]"]
  node_database[("App database<br/>[database.py]")]
  node_diagnostics["Logs and diagnostics<br/>[diagnostics.py]"]
end

subgraph group_marketing["Marketing site"]
  node_site["Marketing pages<br/>[page.tsx]"]
  node_feedback["Feedback endpoint<br/>[route.ts]"]
  node_visits["Visit endpoint<br/>[route.ts]"]
  node_evidence["Evidence endpoint<br/>[route.ts]"]
  node_marketingdata[("Marketing data<br/>[tidb.ts]")]
end

node_user(("Audora user"))
node_apple{{"Apple Music"}}
node_dockerengine{{"Docker Engine"}}
node_files[("Local music files")]
node_visitor(("Site visitor"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_pages
node_app -->|"checks setup"| node_store
node_pages -->|"requests actions"| node_store
node_store -->|"sends requests"| node_api
node_api -->|"HTTP calls"| node_server
node_app -->|"subscribes"| node_websocket
node_websocket -->|"receives events"| node_server
node_electron -->|"starts backend"| node_process
node_process -->|"launches"| node_server
node_server -->|"runs setup"| node_setup
node_setup -->|"manages images"| node_docker
node_docker -->|"controls containers"| node_dockerengine
node_server -->|"handles sign-in"| node_auth
node_auth -->|"starts login service"| node_wrapper
node_wrapper -->|"starts container"| node_docker
node_server -->|"dispatches downloads"| node_queue
node_queue -->|"retrieves tracks"| node_downloader
node_downloader -->|"fetches audio"| node_apple
node_downloader -->|"uses decryptor"| node_wrapper
node_queue -->|"converts tracks"| node_converter
node_queue -->|"records downloads"| node_library
node_converter -->|"writes FLAC"| node_files
node_library -->|"reads and writes"| node_database
node_library -->|"organizes tracks"| node_files
node_server -->|"serves diagnostics"| node_diagnostics
node_visitor -->|"views"| node_site
node_site -->|"records visit"| node_visits
node_site -->|"loads evidence"| node_evidence
node_site -->|"submits feedback"| node_feedback
node_feedback -->|"saves feedback"| node_marketingdata
node_visits -->|"saves visit"| node_marketingdata
node_evidence -->|"reads evidence"| node_marketingdata

click node_app "https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/src/App.tsx"
click node_pages "https://github.com/utkarsh-wadalkar/audora/tree/main/frontend/src/pages"
click node_store "https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/src/store/useAppStore.ts"
click node_api "https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/src/api/client.ts"
click node_websocket "https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/src/hooks/useWebSocket.ts"
click node_electron "https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/electron/main.js"
click node_process "https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/electron/backend-process-controller.js"
click node_server "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/app.py"
click node_setup "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/setup_manager.py"
click node_docker "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/docker_manager.py"
click node_auth "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/auth_manager.py"
click node_wrapper "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/wrapper_manager.py"
click node_queue "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/queue_processor.py"
click node_downloader "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/download_manager.py"
click node_converter "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/flac_converter.py"
click node_library "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/library_manager.py"
click node_database "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/database.py"
click node_diagnostics "https://github.com/utkarsh-wadalkar/audora/blob/main/backend/diagnostics.py"
click node_site "https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/app/page.tsx"
click node_feedback "https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/app/api/feedback/route.ts"
click node_visits "https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/app/api/visits/route.ts"
click node_evidence "https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/app/api/evidence/route.ts"
click node_marketingdata "https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/lib/tidb.ts"

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_pages,node_store,node_api,node_websocket,node_electron,node_process,node_user toneBlue
class node_server,node_setup,node_docker,node_auth,node_wrapper,node_queue,node_downloader,node_files toneAmber
class node_converter,node_library,node_database,node_diagnostics toneMint
class node_site,node_feedback,node_visits,node_evidence,node_marketingdata toneRose
class node_apple,node_dockerengine,node_visitor toneIndigo
```

## Components

### Desktop app

- [App shell](https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [App pages](https://github.com/utkarsh-wadalkar/audora/tree/main/frontend/src/pages): `frontend/src/pages`
- [App state](https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/src/store/useAppStore.ts): `frontend/src/store/useAppStore.ts`
- [API client](https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Live events](https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/src/hooks/useWebSocket.ts): `frontend/src/hooks/useWebSocket.ts`
- [Electron host](https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/electron/main.js): `frontend/electron/main.js`
- [Backend process](https://github.com/utkarsh-wadalkar/audora/blob/main/frontend/electron/backend-process-controller.js): `frontend/electron/backend-process-controller.js`

### Backend workflow

- [API and events](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/app.py): `backend/app.py`
- [First-run setup](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/setup_manager.py): `backend/setup_manager.py`
- [Docker control](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/docker_manager.py): `backend/docker_manager.py`
- [Music authentication](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/auth_manager.py): `backend/auth_manager.py`
- [Wrapper service](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/wrapper_manager.py): `backend/wrapper_manager.py`
- [Download queue](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/queue_processor.py): `backend/queue_processor.py`
- [Track retrieval](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/download_manager.py): `backend/download_manager.py`

### Local music

- [FLAC conversion](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/flac_converter.py): `backend/flac_converter.py`
- [Library and playback](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/library_manager.py): `backend/library_manager.py`
- [App database](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/database.py): `backend/database.py`
- [Logs and diagnostics](https://github.com/utkarsh-wadalkar/audora/blob/main/backend/diagnostics.py): `backend/diagnostics.py`

### Marketing site

- [Marketing pages](https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/app/page.tsx): `marketing/app/page.tsx`
- [Feedback endpoint](https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/app/api/feedback/route.ts): `marketing/app/api/feedback/route.ts`
- [Visit endpoint](https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/app/api/visits/route.ts): `marketing/app/api/visits/route.ts`
- [Evidence endpoint](https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/app/api/evidence/route.ts): `marketing/app/api/evidence/route.ts`
- [Marketing data](https://github.com/utkarsh-wadalkar/audora/blob/main/marketing/lib/tidb.ts): `marketing/lib/tidb.ts`

### Other components

- **Audora user**
- **Apple Music**
- **Docker Engine**
- **Local music files**
- **Site visitor**

## Connections

- Audora user → App shell: uses
- App shell → App pages: routes to
- App shell → App state: checks setup
- App pages → App state: requests actions
- App state → API client: sends requests
- API client → API and events: HTTP calls
- App shell → Live events: subscribes
- Live events → API and events: receives events
- Electron host → Backend process: starts backend
- Backend process → API and events: launches
- API and events → First-run setup: runs setup
- First-run setup → Docker control: manages images
- Docker control → Docker Engine: controls containers
- API and events → Music authentication: handles sign-in
- Music authentication → Wrapper service: starts login service
- Wrapper service → Docker control: starts container
- API and events → Download queue: dispatches downloads
- Download queue → Track retrieval: retrieves tracks
- Track retrieval → Apple Music: fetches audio
- Track retrieval → Wrapper service: uses decryptor
- Download queue → FLAC conversion: converts tracks
- Download queue → Library and playback: records downloads
- FLAC conversion → Local music files: writes FLAC
- Library and playback → App database: reads and writes
- Library and playback → Local music files: organizes tracks
- API and events → Logs and diagnostics: serves diagnostics
- Site visitor → Marketing pages: views
- Marketing pages → Visit endpoint: records visit
- Marketing pages → Evidence endpoint: loads evidence
- Marketing pages → Feedback endpoint: submits feedback
- Feedback endpoint → Marketing data: saves feedback
- Visit endpoint → Marketing data: saves visit
- Evidence endpoint → Marketing data: reads evidence