# as-aigc/transcripthub architecture

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

- Interactive diagram: https://gitdiagram.com/as-aigc/transcripthub
- Repository: https://github.com/as-aigc/transcripthub

## Overview

TranscriptHub is an AI audio-transcription platform with a Go web frontend and a Node.js backend. The main workflow is user upload → task API and scheduling → WhisperX transcription → task-status/result retrieval and download. The backend also documents authentication, multiple audio and output formats, HTTPS, and clustered workers; logging and SQL persistence support these stages. The README describes the frontend/API/backend boundary, while several frontend and worker connections are not visible in the sampled source, so those edges are marked unverified.

Main entry points: [`apps/backend/main.js`](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/main.js) (HTTPS API and workers), [`apps/backend/controller/task_controller.js`](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/controller/task_controller.js) (Task endpoints), [`apps/backend/services/task_service.js`](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/services/task_service.js) (Task lifecycle), [`apps/frontend/router.go`](https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/router.go) (Web server routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Go frontend"]
  node_web_ui["Web interface<br/>[index.tpl]"]
  node_go_router["Web server routes<br/>[router.go]"]
  node_upload["Audio upload<br/>[upload.go]"]
  node_file_handling["File handling<br/>[writefile.go]"]
  node_job_views["Job and transcript views<br/>[jobs.go]"]
end

subgraph group_api["Backend API"]
  node_api_server["HTTPS API and workers<br/>[main.js]"]
  node_validation["Request validation<br/>[validate_params.js]"]
  node_task_api["Task endpoints<br/>[task_controller.js]"]
  node_authorization["Access checks<br/>[auth_controller.js]"]
end

subgraph group_processing["Task processing"]
  node_task_service["Task lifecycle<br/>[task_service.js]"]
  node_media_utils["Media validation and duration<br/>[utils.js]"]
  node_whisperx["WhisperX engine"]
  node_result_files["Transcription outputs<br/>[config.js]"]
  node_notification["Completion notification<br/>[utils.js]"]
end

subgraph group_persistence["Persistence and operations"]
  node_sql_store[("SQL task and access data<br/>[task.sql]")]
  node_query_templates["SQL query templates<br/>[query_constants.js]"]
  node_db_access["Database connections<br/>[db.js]"]
  node_logging["Logging<br/>[logger.js]"]
end

node_user(("User"))

node_user -->|"uses"| node_web_ui
node_web_ui -.->|"interacts with"| node_go_router
node_go_router -.->|"routes upload"| node_upload
node_upload -.->|"stores audio"| node_file_handling
node_go_router -.->|"calls API"| node_api_server
node_api_server -->|"validates requests"| node_validation
node_api_server -->|"routes tasks"| node_task_api
node_task_api -->|"checks access"| node_authorization
node_task_api -->|"manages tasks"| node_task_service
node_task_api -->|"checks duration"| node_media_utils
node_task_service -->|"queries database"| node_db_access
node_authorization -->|"queries access"| node_db_access
node_db_access -->|"uses queries"| node_query_templates
node_query_templates -->|"reads and writes"| node_sql_store
node_task_service -.->|"dispatches work"| node_whisperx
node_whisperx -.->|"produces outputs"| node_result_files
node_task_api -->|"serves downloads"| node_result_files
node_api_server -->|"sends updates"| node_notification
node_notification -.->|"notifies frontend"| node_go_router
node_job_views -.->|"requests status"| node_api_server
node_api_server -->|"records events"| node_logging
node_task_service -->|"records task events"| node_logging

click node_web_ui "https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/www/template/index.tpl"
click node_go_router "https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/router.go"
click node_upload "https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/upload.go"
click node_file_handling "https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/writefile.go"
click node_job_views "https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/jobs.go"
click node_api_server "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/main.js"
click node_validation "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/middlewares/validate_params.js"
click node_task_api "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/controller/task_controller.js"
click node_authorization "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/controller/auth_controller.js"
click node_task_service "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/services/task_service.js"
click node_media_utils "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/utils.js"
click node_whisperx "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/scripts/exec_whisperx_task_v1.2.py"
click node_result_files "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/config.js"
click node_notification "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/utils.js"
click node_sql_store "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/sql/task.sql"
click node_query_templates "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/query_constants.js"
click node_db_access "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/db.js"
click node_logging "https://github.com/as-aigc/transcripthub/blob/main/apps/backend/logger.js"

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_web_ui,node_go_router,node_upload,node_file_handling,node_job_views,node_user toneBlue
class node_api_server,node_validation,node_task_api,node_authorization toneAmber
class node_task_service,node_media_utils,node_whisperx,node_result_files,node_notification toneMint
class node_sql_store,node_query_templates,node_db_access,node_logging toneRose
```

## Components

### Go frontend

- [Web interface](https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/www/template/index.tpl): `apps/frontend/www/template/index.tpl`
- [Web server routes](https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/router.go): `apps/frontend/router.go`
- [Audio upload](https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/upload.go): `apps/frontend/upload.go`
- [File handling](https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/writefile.go): `apps/frontend/writefile.go`
- [Job and transcript views](https://github.com/as-aigc/transcripthub/blob/main/apps/frontend/jobs.go): `apps/frontend/jobs.go`

### Backend API

- [HTTPS API and workers](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/main.js): `apps/backend/main.js`
- [Request validation](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/middlewares/validate_params.js): `apps/backend/middlewares/validate_params.js`
- [Task endpoints](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/controller/task_controller.js): `apps/backend/controller/task_controller.js`
- [Access checks](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/controller/auth_controller.js): `apps/backend/controller/auth_controller.js`

### Task processing

- [Task lifecycle](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/services/task_service.js): `apps/backend/services/task_service.js`
- [Media validation and duration](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/utils.js): `apps/backend/utils.js`
- [WhisperX engine](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/scripts/exec_whisperx_task_v1.2.py): `apps/backend/scripts/exec_whisperx_task_v1.2.py`
- [Transcription outputs](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/config.js): `apps/backend/config.js`
- [Completion notification](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/utils.js): `apps/backend/utils.js`

### Persistence and operations

- [SQL task and access data](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/sql/task.sql): `apps/backend/sql/task.sql`
- [SQL query templates](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/query_constants.js): `apps/backend/query_constants.js`
- [Database connections](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/db.js): `apps/backend/db.js`
- [Logging](https://github.com/as-aigc/transcripthub/blob/main/apps/backend/logger.js): `apps/backend/logger.js`

### Other components

- **User**

## Connections

- User → Web interface: uses (evidence: `README.md`)
- Web interface → Web server routes: interacts with
- Web server routes → Audio upload: routes upload
- Audio upload → File handling: stores audio
- Web server routes → HTTPS API and workers: calls API (evidence: `README.md`)
- HTTPS API and workers → Request validation: validates requests (evidence: `apps/backend/main.js`)
- HTTPS API and workers → Task endpoints: routes tasks (evidence: `apps/backend/main.js`)
- Task endpoints → Access checks: checks access (evidence: `apps/backend/controller/task_controller.js`)
- Task endpoints → Task lifecycle: manages tasks (evidence: `apps/backend/controller/task_controller.js`)
- Task endpoints → Media validation and duration: checks duration (evidence: `apps/backend/controller/task_controller.js`)
- Task lifecycle → Database connections: queries database (evidence: `apps/backend/services/task_service.js`)
- Access checks → Database connections: queries access (evidence: `apps/backend/controller/auth_controller.js`)
- Database connections → SQL query templates: uses queries (evidence: `apps/backend/db.js`)
- SQL query templates → SQL task and access data: reads and writes (evidence: `apps/backend/query_constants.js`)
- Task lifecycle → WhisperX engine: dispatches work
- WhisperX engine → Transcription outputs: produces outputs
- Task endpoints → Transcription outputs: serves downloads (evidence: `apps/backend/controller/task_controller.js`)
- HTTPS API and workers → Completion notification: sends updates (evidence: `apps/backend/main.js`)
- Completion notification → Web server routes: notifies frontend (evidence: `README.md`)
- Job and transcript views → HTTPS API and workers: requests status (evidence: `README.md`)
- HTTPS API and workers → Logging: records events (evidence: `apps/backend/main.js`)
- Task lifecycle → Logging: records task events (evidence: `apps/backend/services/task_service.js`)
