# yuntian-liu/stellaris architecture

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

- Interactive diagram: https://gitdiagram.com/yuntian-liu/stellaris
- Repository: https://github.com/yuntian-liu/stellaris

## Overview

Stellaris is a subtitle-extraction and AI content-understanding web app. A user submits a video URL or file through the frontend; the backend downloads or extracts audio, transcribes it, optionally segments the transcript, and returns subtitle exports and task history. Users can then request summaries, Markdown notes, or streamed chat. Separate product areas cover accounts, three-currency billing, membership fulfillment, admin operations, and vault storage. The README documents the end-to-end pipeline; several subsystem implementations are unsampled, so their internal links are omitted or marked unverified.

Main entry points: [`backend/main.py`](https://github.com/yuntian-liu/stellaris/blob/main/backend/main.py) (HTTP API), [`frontend/src/hooks/api.js`](https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/hooks/api.js) (API client), [`backend/database.py`](https://github.com/yuntian-liu/stellaris/blob/main/backend/database.py) (SQLite database), [`backend/pipeline/asr.py`](https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/asr.py) (Speech recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["App shell<br/>[App.jsx]"]
  node_home["Submit video<br/>[HomePage.jsx]"]
  node_progress["Task progress<br/>[ProgressPage.jsx]"]
  node_result["Results and chat<br/>[ResultPage.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_media["Media and AI pipeline"]
  node_backend_api["HTTP API<br/>[main.py]"]
  node_download["Media acquisition<br/>[download.py]"]
  node_asr["Speech recognition<br/>[asr.py]"]
  node_transcript["Subtitle processing<br/>[subtitle.py]"]
  node_llm["AI understanding<br/>[llm.py]"]
  node_export["Subtitle export<br/>[export.py]"]
end

subgraph group_identity["Accounts and billing"]
  node_account_ui["Account settings<br/>[SettingsView.jsx]"]
  node_auth_ui["Login and signup<br/>[AuthPage.jsx]"]
  node_auth_state["Auth state<br/>[AuthContext.jsx]"]
  node_auth_api["Auth routes<br/>[router.py]"]
  node_users[("User records<br/>[models.py]")]
  node_billing[("Currency billing<br/>[billing_store.py]")]
  node_membership["Membership webhook<br/>[afdian_store.py]"]
  node_redeem["Redeem codes<br/>[redeem_store.py]"]
end

subgraph group_operations["Admin and support"]
  node_admin_ui["Admin dashboard<br/>[AdminView.jsx]"]
  node_admin_api["Admin endpoints<br/>[main.py]"]
  node_admin_store["Admin services<br/>[admin_store.py]"]
  node_tickets[("Feedback tickets<br/>[ticket_store.py]")]
  node_backup["Database backups<br/>[backup_store.py]"]
end

subgraph group_platform["Platform services"]
  node_model_config["Model settings<br/>[model_store.py]"]
  node_history[("Task history<br/>[history_store.py]")]
  node_database[("SQLite database<br/>[database.py]")]
  node_vault[("User vault<br/>[vault_store.py]")]
  node_chat_store[("Chat storage<br/>[chat_store.py]")]
end

node_user(("Video user"))
node_asr_service{{"Cloud ASR"}}
node_llm_service{{"DeepSeek"}}
node_afdian_service{{"爱发电"}}

node_user -->|"submits URL or file"| node_home
node_home -.->|"requests estimate and task"| node_api_client
node_api_client -.->|"calls API"| node_backend_api
node_backend_api -->|"acquires media"| node_download
node_download -->|"provides audio"| node_asr
node_asr -->|"transcribes audio"| node_asr_service
node_asr -->|"produces transcript"| node_transcript
node_transcript -->|"segments text"| node_llm
node_backend_api -->|"exports subtitles"| node_export
node_backend_api -->|"reports task status"| node_progress
node_backend_api -->|"serves task result"| node_result
node_llm -->|"requests AI output"| node_llm_service
node_llm -->|"reads active model"| node_model_config
node_result -.->|"requests chat and exports"| node_api_client
node_user -->|"signs in or registers"| node_auth_ui
node_auth_ui -->|"sets login state"| node_auth_state
node_auth_state -->|"validates session"| node_api_client
node_auth_api -->|"reads and updates users"| node_users
node_auth_api -->|"uses database session"| node_database
node_account_ui -.->|"requests account data"| node_api_client
node_backend_api -.->|"meters operations"| node_billing
node_membership -->|"fulfills membership"| node_billing
node_afdian_service -->|"sends webhook"| node_membership
node_redeem -->|"applies redemption"| node_billing
node_backend_api -->|"retains task history"| node_history
node_history -->|"stores task records"| node_database
node_backend_api -.->|"serves admin data"| node_admin_ui
node_admin_ui -.->|"requests admin actions"| node_api_client
node_admin_api -->|"delegates admin operations"| node_admin_store
node_admin_api -.->|"manages tickets"| node_tickets
node_admin_api -.->|"manages backups"| node_backup
node_admin_store -.->|"queries product data"| node_database
node_backend_api -->|"handles vault operations"| node_vault
node_backend_api -.->|"persists chat turns"| node_chat_store
node_chat_store -->|"stores chat data"| node_database

click node_app "https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/App.jsx"
click node_home "https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/HomePage.jsx"
click node_progress "https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/ProgressPage.jsx"
click node_result "https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/ResultPage.jsx"
click node_api_client "https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/hooks/api.js"
click node_backend_api "https://github.com/yuntian-liu/stellaris/blob/main/backend/main.py"
click node_download "https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/download.py"
click node_asr "https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/asr.py"
click node_transcript "https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/subtitle.py"
click node_llm "https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/llm.py"
click node_export "https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/export.py"
click node_model_config "https://github.com/yuntian-liu/stellaris/blob/main/backend/model_store.py"
click node_account_ui "https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/SettingsView.jsx"
click node_auth_ui "https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/AuthPage.jsx"
click node_auth_state "https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/contexts/AuthContext.jsx"
click node_auth_api "https://github.com/yuntian-liu/stellaris/blob/main/backend/auth/router.py"
click node_users "https://github.com/yuntian-liu/stellaris/blob/main/backend/auth/models.py"
click node_billing "https://github.com/yuntian-liu/stellaris/blob/main/backend/billing_store.py"
click node_membership "https://github.com/yuntian-liu/stellaris/blob/main/backend/afdian_store.py"
click node_redeem "https://github.com/yuntian-liu/stellaris/blob/main/backend/redeem_store.py"
click node_history "https://github.com/yuntian-liu/stellaris/blob/main/backend/history_store.py"
click node_database "https://github.com/yuntian-liu/stellaris/blob/main/backend/database.py"
click node_admin_ui "https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/AdminView.jsx"
click node_admin_api "https://github.com/yuntian-liu/stellaris/blob/main/backend/main.py"
click node_admin_store "https://github.com/yuntian-liu/stellaris/blob/main/backend/admin_store.py"
click node_tickets "https://github.com/yuntian-liu/stellaris/blob/main/backend/ticket_store.py"
click node_backup "https://github.com/yuntian-liu/stellaris/blob/main/backend/backup_store.py"
click node_vault "https://github.com/yuntian-liu/stellaris/blob/main/backend/vault_store.py"
click node_chat_store "https://github.com/yuntian-liu/stellaris/blob/main/backend/chat_store.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_home,node_progress,node_result,node_api_client,node_user toneBlue
class node_backend_api,node_download,node_asr,node_transcript,node_llm,node_export toneAmber
class node_account_ui,node_auth_ui,node_auth_state,node_auth_api,node_users,node_billing,node_membership,node_redeem toneMint
class node_admin_ui,node_admin_api,node_admin_store,node_tickets,node_backup toneRose
class node_model_config,node_history,node_database,node_vault,node_chat_store,node_asr_service,node_llm_service,node_afdian_service toneIndigo
```

## Components

### User experience

- [App shell](https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Submit video](https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/HomePage.jsx): `frontend/src/pages/HomePage.jsx`
- [Task progress](https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/ProgressPage.jsx): `frontend/src/pages/ProgressPage.jsx`
- [Results and chat](https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/ResultPage.jsx): `frontend/src/pages/ResultPage.jsx`
- [API client](https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/hooks/api.js): `frontend/src/hooks/api.js`

### Media and AI pipeline

- [HTTP API](https://github.com/yuntian-liu/stellaris/blob/main/backend/main.py): `backend/main.py`
- [Media acquisition](https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/download.py): `backend/pipeline/download.py`
- [Speech recognition](https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/asr.py): `backend/pipeline/asr.py`
- [Subtitle processing](https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/subtitle.py): `backend/pipeline/subtitle.py`
- [AI understanding](https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/llm.py): `backend/pipeline/llm.py`
- [Subtitle export](https://github.com/yuntian-liu/stellaris/blob/main/backend/pipeline/export.py): `backend/pipeline/export.py`

### Accounts and billing

- [Account settings](https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/SettingsView.jsx): `frontend/src/pages/SettingsView.jsx`
- [Login and signup](https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/AuthPage.jsx): `frontend/src/pages/AuthPage.jsx`
- [Auth state](https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/contexts/AuthContext.jsx): `frontend/src/contexts/AuthContext.jsx`
- [Auth routes](https://github.com/yuntian-liu/stellaris/blob/main/backend/auth/router.py): `backend/auth/router.py`
- [User records](https://github.com/yuntian-liu/stellaris/blob/main/backend/auth/models.py): `backend/auth/models.py`
- [Currency billing](https://github.com/yuntian-liu/stellaris/blob/main/backend/billing_store.py): `backend/billing_store.py`
- [Membership webhook](https://github.com/yuntian-liu/stellaris/blob/main/backend/afdian_store.py): `backend/afdian_store.py`
- [Redeem codes](https://github.com/yuntian-liu/stellaris/blob/main/backend/redeem_store.py): `backend/redeem_store.py`

### Admin and support

- [Admin dashboard](https://github.com/yuntian-liu/stellaris/blob/main/frontend/src/pages/AdminView.jsx): `frontend/src/pages/AdminView.jsx`
- [Admin endpoints](https://github.com/yuntian-liu/stellaris/blob/main/backend/main.py): `backend/main.py`
- [Admin services](https://github.com/yuntian-liu/stellaris/blob/main/backend/admin_store.py): `backend/admin_store.py`
- [Feedback tickets](https://github.com/yuntian-liu/stellaris/blob/main/backend/ticket_store.py): `backend/ticket_store.py`
- [Database backups](https://github.com/yuntian-liu/stellaris/blob/main/backend/backup_store.py): `backend/backup_store.py`

### Platform services

- [Model settings](https://github.com/yuntian-liu/stellaris/blob/main/backend/model_store.py): `backend/model_store.py`
- [Task history](https://github.com/yuntian-liu/stellaris/blob/main/backend/history_store.py): `backend/history_store.py`
- [SQLite database](https://github.com/yuntian-liu/stellaris/blob/main/backend/database.py): `backend/database.py`
- [User vault](https://github.com/yuntian-liu/stellaris/blob/main/backend/vault_store.py): `backend/vault_store.py`
- [Chat storage](https://github.com/yuntian-liu/stellaris/blob/main/backend/chat_store.py): `backend/chat_store.py`

### Other components

- **Video user**
- **Cloud ASR**
- **DeepSeek**
- **爱发电**

## Connections

- Video user → Submit video: submits URL or file
- Submit video → API client: requests estimate and task
- API client → HTTP API: calls API
- HTTP API → Media acquisition: acquires media (evidence: `backend/main.py`)
- Media acquisition → Speech recognition: provides audio
- Speech recognition → Cloud ASR: transcribes audio
- Speech recognition → Subtitle processing: produces transcript
- Subtitle processing → AI understanding: segments text
- HTTP API → Subtitle export: exports subtitles (evidence: `backend/main.py`)
- HTTP API → Task progress: reports task status
- HTTP API → Results and chat: serves task result
- AI understanding → DeepSeek: requests AI output (evidence: `backend/pipeline/llm.py`)
- AI understanding → Model settings: reads active model (evidence: `backend/pipeline/llm.py`)
- Results and chat → API client: requests chat and exports (evidence: `frontend/src/pages/ResultPage.jsx`)
- Video user → Login and signup: signs in or registers
- Login and signup → Auth state: sets login state (evidence: `frontend/src/pages/AuthPage.jsx`)
- Auth state → API client: validates session (evidence: `frontend/src/contexts/AuthContext.jsx`)
- Auth routes → User records: reads and updates users (evidence: `backend/auth/router.py`)
- Auth routes → SQLite database: uses database session (evidence: `backend/auth/router.py`)
- Account settings → API client: requests account data
- HTTP API → Currency billing: meters operations (evidence: `backend/main.py`)
- Membership webhook → Currency billing: fulfills membership
- 爱发电 → Membership webhook: sends webhook
- Redeem codes → Currency billing: applies redemption (evidence: `backend/redeem_store.py`)
- HTTP API → Task history: retains task history (evidence: `backend/main.py`)
- Task history → SQLite database: stores task records (evidence: `backend/history_store.py`)
- HTTP API → Admin dashboard: serves admin data
- Admin dashboard → API client: requests admin actions (evidence: `frontend/src/pages/AdminView.jsx`)
- Admin endpoints → Admin services: delegates admin operations (evidence: `backend/main.py`)
- Admin endpoints → Feedback tickets: manages tickets (evidence: `backend/main.py`)
- Admin endpoints → Database backups: manages backups (evidence: `backend/main.py`)
- Admin services → SQLite database: queries product data
- HTTP API → User vault: handles vault operations (evidence: `backend/main.py`)
- HTTP API → Chat storage: persists chat turns (evidence: `backend/main.py`)
- Chat storage → SQLite database: stores chat data (evidence: `backend/chat_store.py`)
