# mudybluez/ai-transcription-platform architecture

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

- Interactive diagram: https://gitdiagram.com/mudybluez/ai-transcription-platform
- Repository: https://github.com/mudybluez/ai-transcription-platform

## Overview

ZenScribe is a microservices platform that turns uploaded files or YouTube links into multilingual transcripts and AI study materials. Users enter through the React client, submit media, and receive processed reports, mind maps, and notifications; account, billing, search, and administration provide supporting capabilities. The README documents the service boundaries and major features; source-index references and excerpts establish several internal calls, while some gateway routing and integrations are documented rather than shown in sampled code.

Main entry points: [`frontend/src/App.jsx`](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/App.jsx) (React application), [`api-gateway/src/index.js`](https://github.com/mudybluez/ai-transcription-platform/blob/main/api-gateway/src/index.js) (API gateway), [`frontend/src/pages/Dashboard.jsx`](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/Dashboard.jsx) (Dashboard), [`services/user-service/src/index.js`](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/user-service/src/index.js) (User service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["React application<br/>[App.jsx]"]
  node_login["Login<br/>[Login.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_profile["Profile and billing<br/>[Profile.jsx]"]
  node_admin["Admin panel<br/>[AdminPanel.jsx]"]
  node_globalmap["Global mind maps<br/>[GlobalMindMap.jsx]"]
  node_mindmapview["Mind map view<br/>[MindMap.jsx]"]
  node_landing["Landing page<br/>[LandingPage.jsx]"]
  node_hero["Hero animation<br/>[HeroParticles.jsx]"]
  node_notifications["Notifications UI"]
  node_socket["Shared WebSocket<br/>[sharedSocket.js]"]
  node_api["API client<br/>[api.js]"]
end

subgraph group_edge["API and accounts"]
  node_gateway["API gateway<br/>[index.js]"]
  node_usersvc["User service<br/>[index.js]"]
  node_userdb["User data access<br/>[db.js]"]
  node_email["Email delivery<br/>[emailService.js]"]
  node_nginx["Nginx entry point"]
end

subgraph group_media["Media processing"]
  node_upload["Upload service<br/>[index.js]"]
  node_uploaddb["Upload data access<br/>[db.js]"]
  node_queue["RabbitMQ jobs"]
  node_worker["Processing worker<br/>[worker.py]"]
  node_aicore["Transcription and analysis<br/>[ai_core.py]"]
  node_aidb["Processing persistence<br/>[db.py]"]
end

subgraph group_insights["Search and learning"]
  node_search["Search service<br/>[index.js]"]
  node_searchdb["Search data access<br/>[db.js]"]
  node_cache[("Redis cache<br/>[redisClient.js]")]
  node_proxy["Proxy usage stats"]
  node_mindmapsvc["Mind map service<br/>[main.py]"]
end

subgraph group_state["Platform state"]
  node_postgres[("PostgreSQL")]
  node_stripe["Stripe / PayPal"]
end

node_user(("Platform user"))

node_user -->|"opens app"| node_nginx
node_nginx -->|"serves SPA"| node_app
node_nginx -->|"proxies API"| node_gateway
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_profile
node_app -->|"routes to"| node_admin
node_app -->|"routes to"| node_globalmap
node_app -->|"routes to"| node_landing
node_dashboard -->|"requests data"| node_api
node_dashboard -->|"renders"| node_mindmapview
node_dashboard -->|"renders"| node_hero
node_dashboard -->|"renders"| node_notifications
node_landing -->|"renders"| node_hero
node_notifications -->|"fetches notices"| node_api
node_notifications -->|"subscribes"| node_socket
node_api -->|"sends API requests"| node_gateway
node_gateway -->|"routes requests"| node_usersvc
node_gateway -->|"routes requests"| node_upload
node_gateway -->|"routes requests"| node_search
node_gateway -->|"routes requests"| node_mindmapsvc
node_gateway -->|"manages WebSockets"| node_socket
node_usersvc -->|"uses"| node_userdb
node_usersvc -->|"sends mail"| node_email
node_usersvc -.->|"integrates billing"| node_stripe
node_upload -->|"uses"| node_uploaddb
node_upload -->|"publishes jobs"| node_queue
node_queue -.->|"delivers jobs"| node_worker
node_worker -->|"calls analysis"| node_aicore
node_worker -->|"updates and saves"| node_aidb
node_worker -->|"posts mind map"| node_mindmapsvc
node_search -->|"queries data"| node_searchdb
node_search -->|"uses cache"| node_cache
node_search -->|"gets proxy stats"| node_proxy
node_proxy -->|"queries totals"| node_searchdb
node_userdb -.->|"reads and writes"| node_postgres
node_uploaddb -.->|"reads and writes"| node_postgres
node_aidb -.->|"persists results"| node_postgres
node_searchdb -.->|"queries transcriptions"| node_postgres

click node_app "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/App.jsx"
click node_login "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/Login.jsx"
click node_dashboard "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/Dashboard.jsx"
click node_profile "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/Profile.jsx"
click node_admin "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/AdminPanel.jsx"
click node_globalmap "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/GlobalMindMap.jsx"
click node_mindmapview "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/MindMap.jsx"
click node_landing "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/LandingPage.jsx"
click node_hero "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/HeroParticles.jsx"
click node_notifications "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/components/NotificationsBell.jsx"
click node_socket "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/utils/sharedSocket.js"
click node_api "https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/api.js"
click node_gateway "https://github.com/mudybluez/ai-transcription-platform/blob/main/api-gateway/src/index.js"
click node_usersvc "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/user-service/src/index.js"
click node_userdb "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/user-service/src/db.js"
click node_email "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/user-service/src/emailService.js"
click node_upload "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/upload-service/src/index.js"
click node_uploaddb "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/upload-service/src/db.js"
click node_worker "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/ai-processing-service/worker.py"
click node_aicore "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/ai-processing-service/ai_core.py"
click node_aidb "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/ai-processing-service/db.py"
click node_search "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/search-service/src/index.js"
click node_searchdb "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/search-service/src/db.js"
click node_cache "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/search-service/src/redisClient.js"
click node_proxy "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/search-service/src/astroproxyService.js"
click node_mindmapsvc "https://github.com/mudybluez/ai-transcription-platform/blob/main/services/mindmap-service/src/main.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_login,node_dashboard,node_profile,node_admin,node_globalmap,node_mindmapview,node_landing,node_hero,node_notifications,node_socket,node_api,node_user toneBlue
class node_gateway,node_usersvc,node_userdb,node_email,node_nginx toneAmber
class node_upload,node_uploaddb,node_queue,node_worker,node_aicore,node_aidb toneMint
class node_search,node_searchdb,node_cache,node_proxy,node_mindmapsvc toneRose
class node_postgres,node_stripe toneIndigo
```

## Components

### Web client

- [React application](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Login](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Dashboard](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Profile and billing](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/Profile.jsx): `frontend/src/pages/Profile.jsx`
- [Admin panel](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/AdminPanel.jsx): `frontend/src/pages/AdminPanel.jsx`
- [Global mind maps](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/GlobalMindMap.jsx): `frontend/src/pages/GlobalMindMap.jsx`
- [Mind map view](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/MindMap.jsx): `frontend/src/pages/MindMap.jsx`
- [Landing page](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/LandingPage.jsx): `frontend/src/pages/LandingPage.jsx`
- [Hero animation](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/pages/HeroParticles.jsx): `frontend/src/pages/HeroParticles.jsx`
- [Notifications UI](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/components/NotificationsBell.jsx): `frontend/src/components/NotificationsBell.jsx`
- [Shared WebSocket](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/utils/sharedSocket.js): `frontend/src/utils/sharedSocket.js`
- [API client](https://github.com/mudybluez/ai-transcription-platform/blob/main/frontend/src/api.js): `frontend/src/api.js`

### API and accounts

- [API gateway](https://github.com/mudybluez/ai-transcription-platform/blob/main/api-gateway/src/index.js): `api-gateway/src/index.js`
- [User service](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/user-service/src/index.js): `services/user-service/src/index.js`
- [User data access](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/user-service/src/db.js): `services/user-service/src/db.js`
- [Email delivery](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/user-service/src/emailService.js): `services/user-service/src/emailService.js`
- **Nginx entry point**

### Media processing

- [Upload service](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/upload-service/src/index.js): `services/upload-service/src/index.js`
- [Upload data access](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/upload-service/src/db.js): `services/upload-service/src/db.js`
- **RabbitMQ jobs**
- [Processing worker](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/ai-processing-service/worker.py): `services/ai-processing-service/worker.py`
- [Transcription and analysis](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/ai-processing-service/ai_core.py): `services/ai-processing-service/ai_core.py`
- [Processing persistence](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/ai-processing-service/db.py): `services/ai-processing-service/db.py`

### Search and learning

- [Search service](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/search-service/src/index.js): `services/search-service/src/index.js`
- [Search data access](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/search-service/src/db.js): `services/search-service/src/db.js`
- [Redis cache](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/search-service/src/redisClient.js): `services/search-service/src/redisClient.js`
- [Proxy usage stats](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/search-service/src/astroproxyService.js): `services/search-service/src/astroproxyService.js`
- [Mind map service](https://github.com/mudybluez/ai-transcription-platform/blob/main/services/mindmap-service/src/main.py): `services/mindmap-service/src/main.py`

### Platform state

- **PostgreSQL**
- **Stripe / PayPal**

### Other components

- **Platform user**

## Connections

- Platform user → Nginx entry point: opens app (evidence: `README.md`)
- Nginx entry point → React application: serves SPA (evidence: `README.md`)
- Nginx entry point → API gateway: proxies API (evidence: `README.md`)
- React application → Login: routes to (evidence: `frontend/src/App.jsx`)
- React application → Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- React application → Profile and billing: routes to (evidence: `frontend/src/App.jsx`)
- React application → Admin panel: routes to (evidence: `frontend/src/App.jsx`)
- React application → Global mind maps: routes to (evidence: `frontend/src/App.jsx`)
- React application → Landing page: routes to (evidence: `frontend/src/App.jsx`)
- Dashboard → API client: requests data (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Mind map view: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Hero animation: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Notifications UI: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Landing page → Hero animation: renders (evidence: `frontend/src/pages/LandingPage.jsx`)
- Notifications UI → API client: fetches notices (evidence: `frontend/src/components/NotificationsBell.jsx`)
- Notifications UI → Shared WebSocket: subscribes (evidence: `frontend/src/components/NotificationsBell.jsx`)
- API client → API gateway: sends API requests (evidence: `frontend/src/api.js`)
- API gateway → User service: routes requests (evidence: `README.md`)
- API gateway → Upload service: routes requests (evidence: `README.md`)
- API gateway → Search service: routes requests (evidence: `README.md`)
- API gateway → Mind map service: routes requests (evidence: `README.md`)
- API gateway → Shared WebSocket: manages WebSockets (evidence: `README.md`)
- User service → User data access: uses (evidence: `services/user-service/src/index.js`)
- User service → Email delivery: sends mail (evidence: `services/user-service/src/index.js`)
- User service → Stripe / PayPal: integrates billing (evidence: `README.md`)
- Upload service → Upload data access: uses (evidence: `services/upload-service/src/index.js`)
- Upload service → RabbitMQ jobs: publishes jobs (evidence: `README.md`)
- RabbitMQ jobs → Processing worker: delivers jobs (evidence: `README.md`)
- Processing worker → Transcription and analysis: calls analysis (evidence: `services/ai-processing-service/worker.py`)
- Processing worker → Processing persistence: updates and saves (evidence: `services/ai-processing-service/worker.py`)
- Processing worker → Mind map service: posts mind map (evidence: `services/ai-processing-service/worker.py`)
- Search service → Search data access: queries data (evidence: `services/search-service/src/index.js`)
- Search service → Redis cache: uses cache (evidence: `services/search-service/src/index.js`)
- Search service → Proxy usage stats: gets proxy stats (evidence: `services/search-service/src/index.js`)
- Proxy usage stats → Search data access: queries totals (evidence: `services/search-service/src/astroproxyService.js`)
- User data access → PostgreSQL: reads and writes (evidence: `README.md`)
- Upload data access → PostgreSQL: reads and writes (evidence: `README.md`)
- Processing persistence → PostgreSQL: persists results (evidence: `README.md`)
- Search data access → PostgreSQL: queries transcriptions (evidence: `README.md`)
