# manish-qw/meet-scribe architecture

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

- Interactive diagram: https://gitdiagram.com/manish-qw/meet-scribe
- Repository: https://github.com/manish-qw/meet-scribe

## Overview

1. **System shape**
   - Meet Scribe is a two-tier app: a **React/Vite frontend** and a **FastAPI backend**.
   - The backend is not just an API; it also owns the **meeting bot runtime**, **real-time transcript streaming**, and **AI summarization** pipeline.

2. **Frontend boundary**
   - `frontend/src` is the presentation layer: landing/login/dashboard/meeting pages plus reusable UI components.
   - `src/lib/api.ts` is the HTTP client boundary to the backend.
   - `src/hooks/useMeetingSocket.ts` is the real-time boundary for live meeting updates.
   - `src/lib/firebase.ts` and `useAuth.ts` show the frontend relies on **Firebase Auth** for user identity/session state.

3. **User-facing flows**
   - The main user path is: sign in → submit a Google Meet link → monitor live transcript/status → view summary/dashboard history.
   - `ProtectedRoute.tsx` indicates authenticated access gates around dashboard/meeting views.
   - `DashboardPage`, `MeetingPage`, and `LandingPage` reflect a split between marketing, authenticated workspace, and live session UI.

4. **Backend API layer**
   - `backend/app/api/routes/auth.py` and `meetings.py` expose the HTTP endpoints.
   - This layer likely handles login/token validation, meeting creation/history lookup, and returning persisted meeting artifacts.
   - `backend/app/core/dependencies.py` and `config.py` centralize request-scoped wiring and environment-driven configuration.

5. **Real-time event path**
   - `backend/app/api/websocket/manager.py` and `events.py` implement the WebSocket channel used for low-latency transcript/status delivery.
   - Data flow is backend-push rather than polling: the frontend subscribes, and the backend streams updates as the bot captures them.
   - This is the key live-telemetry boundary in the architecture.

6. **Bot execution subsystem**
   - `backend/app/bot/browser.py` and `meet_bot.py` are the autonomous meeting worker.
   - It uses **Playwright + headless Chromium** to join Google Meet and capture captions/transcript content.
   - This subsystem is isolated from the API process logic, which is important for reliability and resource control.

7. **Process management and cleanup**
   - `backend/app/core/process_pool.py` suggests bot work is dispatched into separate processes rather than running inline with HTTP handlers.
   - `zombie_reaper.py` indicates the backend actively cleans up orphaned worker/bot processes.
   - This separation prevents long-running meeting joins from blocking API responsiveness.

8. **Transcript and synthesis pipeline**
   - `backend/app/bot/transcript.py` likely normalizes raw caption stream into usable transcript chunks.
   - `backend/app/services/gemini.py` is the AI synthesis layer, producing summaries, action items, and key takeaways after or during the meeting.
   - The architecture is therefore: capture text → stream live → finalize into structured AI output.

9. **Persistence and external services**
   - `firebase_service.py` points to **Firebase/Firestore** as the primary metadata and user-data backend.
   - `firebase_storage.py` and `s3_storage.py` indicate artifact storage is abstracted behind service adapters, likely for transcripts/exports or media-like assets.
   - External dependencies that materially affect the architecture are **Firebase Auth**, **Firestore**, **Google Gemini**, and **Google Meet**.

10. **Deployment topology**
   - The repo is containerized with `docker-compose.yml` and separate Dockerfiles for backend and frontend.
   - The frontend also has an Nginx config, implying production builds are served as static assets behind a web server.
   - Environment-specific files (`frontend/.firebaserc`, `firebase.json`, backend env/config patterns) show the app is designed for Firebase-hosted frontend plus containerized backend services.

11. **What to draw in an architecture diagram**
   - Show four major zones: **browser UI**, **FastAPI API/WebSocket layer**, **bot worker process**, and **external services**.
   - Draw the main data path from frontend → API → bot worker → transcript stream → WebSocket → frontend, then API/bot → Gemini → Firestore/storage for persistence.
   - Treat the bot worker as a distinct runtime boundary, not just a function call inside the API.

Main entry points: [`backend/app/api/routes/meetings.py`](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/api/routes/meetings.py) (Meeting routes), [`backend/app/bot/meet_bot.py`](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/bot/meet_bot.py) (Bot worker), [`frontend/src/pages/DashboardPage.tsx`](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/pages/DashboardPage.tsx) (Dashboard), [`frontend/src/pages/MeetingPage.tsx`](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/pages/MeetingPage.tsx) (Meeting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_landing["Landing<br/>page<br/>[LandingPage.tsx]"]
  node_login["Login<br/>page<br/>[LoginPage.tsx]"]
  node_dashboard["Dashboard<br/>page<br/>[DashboardPage.tsx]"]
  node_meeting["Meeting<br/>page<br/>[MeetingPage.tsx]"]
  node_protected{{"Protected route<br/>guard<br/>[ProtectedRoute.tsx]"}}
  node_meeting_input["Meeting input<br/>ui<br/>[MeetingInput.tsx]"]
  node_live_card["Live status<br/>ui<br/>[LiveStatusCard.tsx]"]
  node_summary_card["Summary card<br/>ui<br/>[SummaryCard.tsx]"]
  node_api_client["API client<br/>http client<br/>[api.ts]"]
  node_meeting_socket["Meeting socket<br/>realtime client"]
  node_auth_hook["Auth hook<br/>session state<br/>[useAuth.ts]"]
end

subgraph group_backend["Backend"]
  node_auth_routes["Auth routes<br/>http api<br/>[auth.py]"]
  node_meeting_routes["Meeting routes<br/>http api<br/>[meetings.py]"]
  node_ws_manager["WS manager<br/>websocket hub<br/>[manager.py]"]
  node_ws_events["WS events<br/>realtime events<br/>[events.py]"]
  node_process_pool["Process pool<br/>worker dispatch<br/>[process_pool.py]"]
  node_bot_worker{{"Bot worker<br/>meeting bot<br/>[meet_bot.py]"}}
  node_browser["Browser runner<br/>playwright runtime<br/>[browser.py]"]
  node_transcript["Transcript parser<br/>pipeline<br/>[transcript.py]"]
  node_gemini["Gemini service<br/>ai synthesis<br/>[gemini.py]"]
  node_firebase_service[("Firebase service<br/>persistence")]
  node_storage[("Artifact storage<br/>storage adapters")]
end

subgraph group_external["External Services"]
  node_firebase_auth{{"Firebase Auth<br/>identity provider"}}
  node_firestore[("Firestore<br/>database")]
  node_google_meet{{"Google Meet<br/>meeting platform"}}
  node_gemini_api{{"Gemini API<br/>llm service"}}
  node_s3[("S3<br/>object storage")]
end

node_landing -->|"sign in"| node_login
node_login -->|"session"| node_auth_hook
node_auth_hook -->|"auth"| node_firebase_auth
node_meeting_input -->|"create meeting"| node_api_client
node_api_client -->|"HTTP"| node_meeting_routes
node_api_client -->|"HTTP"| node_auth_routes
node_protected -->|"gate"| node_dashboard
node_protected -->|"gate"| node_meeting
node_dashboard -->|"start meeting"| node_meeting_input
node_meeting -->|"subscribe"| node_meeting_socket
node_meeting_socket -->|"WS"| node_ws_manager
node_ws_manager -->|"emit"| node_ws_events
node_meeting_routes -->|"dispatch"| node_process_pool
node_process_pool -->|"spawn"| node_bot_worker
node_bot_worker -->|"join"| node_browser
node_browser -->|"connect"| node_google_meet
node_bot_worker -->|"capture"| node_transcript
node_transcript -->|"stream"| node_ws_manager
node_bot_worker -->|"summarize"| node_gemini
node_gemini -->|"llm"| node_gemini_api
node_gemini -->|"result"| node_meeting_routes
node_meeting_routes -->|"persist"| node_firebase_service
node_firebase_service -->|"read/write"| node_firestore
node_meeting_routes -->|"artifacts"| node_storage
node_storage -->|"object store"| node_s3
node_dashboard -->|"view summary"| node_summary_card
node_meeting -->|"view live"| node_live_card

click node_landing "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/pages/LandingPage.tsx"
click node_login "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/pages/LoginPage.tsx"
click node_dashboard "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/pages/DashboardPage.tsx"
click node_meeting "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/pages/MeetingPage.tsx"
click node_protected "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/components/layout/ProtectedRoute.tsx"
click node_meeting_input "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/components/meeting/MeetingInput.tsx"
click node_live_card "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/components/meeting/LiveStatusCard.tsx"
click node_summary_card "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/components/meeting/SummaryCard.tsx"
click node_api_client "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/lib/api.ts"
click node_meeting_socket "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/hooks/useMeetingSocket.ts"
click node_auth_hook "https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/hooks/useAuth.ts"
click node_auth_routes "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/api/routes/auth.py"
click node_meeting_routes "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/api/routes/meetings.py"
click node_ws_manager "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/api/websocket/manager.py"
click node_ws_events "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/api/websocket/events.py"
click node_process_pool "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/core/process_pool.py"
click node_bot_worker "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/bot/meet_bot.py"
click node_browser "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/bot/browser.py"
click node_transcript "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/bot/transcript.py"
click node_gemini "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/services/gemini.py"
click node_firebase_service "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/services/firebase_service.py"
click node_storage "https://github.com/manish-qw/meet-scribe/blob/master/backend/app/services/firebase_storage.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_landing,node_login,node_dashboard,node_meeting,node_protected,node_meeting_input,node_live_card,node_summary_card,node_api_client,node_meeting_socket,node_auth_hook toneBlue
class node_auth_routes,node_meeting_routes,node_ws_manager,node_ws_events,node_process_pool,node_bot_worker,node_browser,node_transcript,node_gemini,node_firebase_service,node_storage toneAmber
class node_firebase_auth,node_firestore,node_google_meet,node_gemini_api,node_s3 toneMint
```

## Components

### Frontend

React/Vite browser app and UI state boundaries

- [Landing](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/pages/LandingPage.tsx): page · Marketing and entry page · `frontend/src/pages/LandingPage.tsx`
- [Login](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/pages/LoginPage.tsx): page · Firebase-backed sign-in flow · `frontend/src/pages/LoginPage.tsx`
- [Dashboard](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/pages/DashboardPage.tsx): page · Authenticated meeting history and overview · `frontend/src/pages/DashboardPage.tsx`
- [Meeting](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/pages/MeetingPage.tsx): page · Live meeting session view · `frontend/src/pages/MeetingPage.tsx`
- [Protected route](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/components/layout/ProtectedRoute.tsx): guard · Authenticated access boundary · `frontend/src/components/layout/ProtectedRoute.tsx`
- [Meeting input](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/components/meeting/MeetingInput.tsx): ui · Submit Google Meet link · `frontend/src/components/meeting/MeetingInput.tsx`
- [Live status](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/components/meeting/LiveStatusCard.tsx): ui · Transcript and status display · `frontend/src/components/meeting/LiveStatusCard.tsx`
- [Summary card](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/components/meeting/SummaryCard.tsx): ui · Meeting summary display · `frontend/src/components/meeting/SummaryCard.tsx`
- [API client](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/lib/api.ts): http client · Frontend boundary to backend routes · `frontend/src/lib/api.ts`
- [Meeting socket](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/hooks/useMeetingSocket.ts): realtime client · WebSocket subscription for live updates · `frontend/src/hooks/useMeetingSocket.ts`
- [Auth hook](https://github.com/manish-qw/meet-scribe/blob/master/frontend/src/hooks/useAuth.ts): session state · Frontend auth/session state management · `frontend/src/hooks/useAuth.ts`

### Backend

FastAPI API, websocket, bot runtime, and services

- [Auth routes](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/api/routes/auth.py): http api · Backend authentication and token validation endpoints · `backend/app/api/routes/auth.py`
- [Meeting routes](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/api/routes/meetings.py): http api · Backend meeting creation and history endpoints · `backend/app/api/routes/meetings.py`
- [WS manager](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/api/websocket/manager.py): websocket hub · Connection lifecycle and broadcast management · `backend/app/api/websocket/manager.py`
- [WS events](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/api/websocket/events.py): realtime events · Transcript and status event definitions · `backend/app/api/websocket/events.py`
- [Process pool](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/core/process_pool.py): worker dispatch · Runs bot work out of process · `backend/app/core/process_pool.py`
- [Bot worker](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/bot/meet_bot.py): meeting bot · Joins meetings and captures captions · `backend/app/bot/meet_bot.py`
- [Browser runner](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/bot/browser.py): playwright runtime · Headless Chromium / Playwright meeting session · `backend/app/bot/browser.py`
- [Transcript parser](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/bot/transcript.py): pipeline · Normalizes raw captions into transcript chunks · `backend/app/bot/transcript.py`
- [Gemini service](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/services/gemini.py): ai synthesis · Generates summaries and action items · `backend/app/services/gemini.py`
- [Firebase service](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/services/firebase_service.py): persistence · Firestore-backed metadata and user data access · `backend/app/services/firebase_service.py`
- [Artifact storage](https://github.com/manish-qw/meet-scribe/blob/master/backend/app/services/firebase_storage.py): storage adapters · Firebase Storage and S3 persistence layer · `backend/app/services/firebase_storage.py`

### External Services

Identity, AI, storage, and meeting platform dependencies

- **Firebase Auth**: identity provider · User authentication and session identity
- **Firestore**: database · Persistent meeting and user records
- **Google Meet**: meeting platform · Target meeting environment joined by bot
- **Gemini API**: llm service · External model backend for synthesis
- **S3**: object storage · Optional artifact storage backend

## Connections

- Landing → Login: sign in · Entry into authenticated flow
- Login → Auth hook: session · Loads and tracks user identity
- Auth hook → Firebase Auth: auth · Uses Firebase for identity/session state
- Meeting input → API client: create meeting · Sends Meet link and request payload
- API client → Meeting routes: HTTP · Backend meeting API call
- API client → Auth routes: HTTP · Token validation and auth-related calls
- Protected route → Dashboard: gate · Authenticated access to workspace
- Protected route → Meeting: gate · Authenticated access to live session
- Dashboard → Meeting input: start meeting · User submits a meeting link
- Meeting → Meeting socket: subscribe · Receives live transcript and status
- Meeting socket → WS manager: WS · Connects to backend websocket channel
- WS manager → WS events: emit · Broadcasts structured live events
- Meeting routes → Process pool: dispatch · Launches meeting bot work asynchronously
- Process pool → Bot worker: spawn · Isolates long-running bot execution
- Bot worker → Browser runner: join · Uses headless browser to enter meeting
- Browser runner → Google Meet: connect · Joins Google Meet session
- Bot worker → Transcript parser: capture · Parses live captions into chunks
- Transcript parser → WS manager: stream · Sends live transcript/status updates
- Bot worker → Gemini service: summarize · Generates meeting summary output
- Gemini service → Gemini API: llm · External synthesis service
- Gemini service → Meeting routes: result · Returns structured summary artifacts
- Meeting routes → Firebase service: persist · Stores meeting metadata and outcomes
- Firebase service → Firestore: read/write · Primary metadata persistence
- Meeting routes → Artifact storage: artifacts · Stores exports and generated files
- Artifact storage → S3: object store · Optional artifact backend
- Dashboard → Summary card: view summary · Displays meeting synthesis
- Meeting → Live status: view live · Displays live transcript/status