# brvieira/whatsapp-transcriber architecture

> Architecture diagram of the GitHub repository brvieira/whatsapp-transcriber, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brvieira/whatsapp-transcriber
- Repository: https://github.com/brvieira/whatsapp-transcriber

## Overview

WhatsApp Transcriber turns an exported chat ZIP into a searchable, readable conversation with original media and audio transcripts. The main path is upload, background extraction and parsing, per-audio transcription, finalization, then conversation viewing with live progress. The README documents the service-level workflow and major UI features; sampled source confirms key API, ingest, parser, and audio-pipeline responsibilities. Some UI and worker implementation details were not sampled, so those links rely on README documentation rather than inspected calls.

Main entry points: [`apps/worker/src/ingest.ts`](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/ingest.ts) (ZIP ingestion), [`packages/db/src/schema.ts`](https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/db/src/schema.ts) (MongoDB), [`apps/web/lib/api.ts`](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/lib/api.ts) (API client), [`apps/api/src/routes/conversations.ts`](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/routes/conversations.ts) (Conversation routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_upload["ZIP upload<br/>[UploadArea.tsx]"]
  node_conversation_ui["Conversation pages"]
  node_chat_ui["Chat display<br/>[ChatView.tsx]"]
  node_participants["Participant panel"]
  node_events_hook["Live progress"]
  node_messages_hook["Message loading<br/>[useMessages.ts]"]
  node_web_api["API client<br/>[api.ts]"]
end

subgraph group_api["API"]
  node_api_routes["HTTP routes<br/>[app.ts]"]
  node_conversations["Conversation routes<br/>[conversations.ts]"]
  node_events["Event stream<br/>[events.ts]"]
  node_messages["Message routes<br/>[messages.ts]"]
  node_media["Media routes<br/>[media.ts]"]
  node_serializers["API serializers<br/>[serializers.ts]"]
end

subgraph group_worker["Background processing"]
  node_ingest["ZIP ingestion<br/>[ingest.ts]"]
  node_safe_extract["Safe extraction<br/>[safeExtract.ts]"]
  node_conversation_state["Conversation state<br/>[conversation.ts]"]
  node_finalize["Finalization<br/>[finalize.ts]"]
  node_transcribe_job["Audio jobs<br/>[transcribe.ts]"]
  node_audio_pipeline["Audio pipeline<br/>[pipeline.ts]"]
  node_ffmpeg["Audio conversion<br/>[ffmpeg.ts]"]
  node_hash["Media hashing<br/>[hash.ts]"]
end

subgraph group_domain["Chat and transcription"]
  node_chat_parser["Chat parser<br/>[index.ts]"]
  node_attachments["Attachment parsing<br/>[attachments.ts]"]
  node_dates["Date parsing<br/>[dates.ts]"]
  node_patterns["Format detection<br/>[patterns.ts]"]
  node_transcribe_provider["Provider interface<br/>[provider.ts]"]
  node_openai["OpenAI transcription<br/>[openai.ts]"]
  node_mock["Mock transcription<br/>[mock.ts]"]
end

subgraph group_data["Storage and queue"]
  node_mongo[("MongoDB<br/>[schema.ts]")]
  node_redis["Redis job queue<br/>[index.ts]"]
  node_disk[("Local media files")]
end

node_user(("Uploader"))

node_user -->|"uploads ZIP"| node_upload
node_upload -->|"sends upload"| node_web_api
node_web_api -->|"calls API"| node_conversations
node_conversations -->|"enqueues ingest"| node_redis
node_conversations -->|"stores upload state"| node_mongo
node_conversations -->|"writes ZIP"| node_disk
node_redis -->|"dispatches job"| node_ingest
node_ingest -->|"extracts archive"| node_safe_extract
node_ingest -->|"parses chat"| node_chat_parser
node_chat_parser -->|"classifies media"| node_attachments
node_chat_parser -->|"interprets dates"| node_dates
node_chat_parser -->|"detects formats"| node_patterns
node_ingest -->|"writes messages"| node_mongo
node_ingest -->|"stores extracted media"| node_disk
node_ingest -->|"updates status"| node_conversation_state
node_ingest -->|"schedules audio jobs"| node_redis
node_transcribe_job -->|"processes audio"| node_audio_pipeline
node_audio_pipeline -->|"converts and splits"| node_ffmpeg
node_audio_pipeline -->|"requests transcription"| node_transcribe_provider
node_transcribe_provider -.->|"uses provider"| node_openai
node_transcribe_provider -.->|"uses provider"| node_mock
node_transcribe_job -->|"stores transcripts"| node_mongo
node_ingest -->|"hashes media"| node_hash
node_finalize -->|"saves final stats"| node_mongo
node_redis -->|"dispatches after audio"| node_finalize
node_web_api -->|"opens SSE"| node_events
node_events -->|"watches progress"| node_mongo
node_events -->|"streams updates"| node_events_hook
node_web_api -->|"requests messages"| node_messages
node_messages -->|"reads messages"| node_mongo
node_messages -->|"formats responses"| node_serializers
node_conversations -->|"formats summaries"| node_serializers
node_web_api -.->|"requests media"| node_media
node_media -->|"serves media"| node_disk
node_conversation_ui -.->|"loads conversation"| node_messages_hook
node_conversation_ui -->|"shows progress"| node_events_hook
node_conversation_ui -.->|"renders chat"| node_chat_ui
node_chat_ui -->|"shows participants"| node_participants

click node_upload "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/components/UploadArea.tsx"
click node_conversation_ui "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/components/ConversationView.tsx"
click node_chat_ui "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/components/chat/ChatView.tsx"
click node_participants "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/components/chat/ParticipantsPanel.tsx"
click node_events_hook "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/hooks/useConversationEvents.ts"
click node_messages_hook "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/hooks/useMessages.ts"
click node_web_api "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/lib/api.ts"
click node_api_routes "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/app.ts"
click node_conversations "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/routes/conversations.ts"
click node_events "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/routes/events.ts"
click node_messages "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/routes/messages.ts"
click node_media "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/routes/media.ts"
click node_serializers "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/serializers.ts"
click node_ingest "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/ingest.ts"
click node_safe_extract "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/zip/safeExtract.ts"
click node_conversation_state "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/conversation.ts"
click node_finalize "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/finalize.ts"
click node_transcribe_job "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/transcribe.ts"
click node_audio_pipeline "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/transcription/pipeline.ts"
click node_ffmpeg "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/audio/ffmpeg.ts"
click node_hash "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/media/hash.ts"
click node_chat_parser "https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/core/src/parser/index.ts"
click node_attachments "https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/core/src/parser/attachments.ts"
click node_dates "https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/core/src/parser/dates.ts"
click node_patterns "https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/core/src/parser/patterns.ts"
click node_transcribe_provider "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/transcription/provider.ts"
click node_openai "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/transcription/openai.ts"
click node_mock "https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/transcription/mock.ts"
click node_mongo "https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/db/src/schema.ts"
click node_redis "https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/queue/src/index.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_upload,node_conversation_ui,node_chat_ui,node_participants,node_events_hook,node_messages_hook,node_web_api toneBlue
class node_api_routes,node_conversations,node_events,node_messages,node_media,node_serializers toneAmber
class node_ingest,node_safe_extract,node_conversation_state,node_finalize,node_transcribe_job,node_audio_pipeline,node_ffmpeg,node_hash toneMint
class node_chat_parser,node_attachments,node_dates,node_patterns,node_transcribe_provider,node_openai,node_mock toneRose
class node_mongo,node_redis,node_disk,node_user toneIndigo
```

## Components

### Web interface

- [ZIP upload](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/components/UploadArea.tsx): `apps/web/components/UploadArea.tsx`
- [Conversation pages](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/components/ConversationView.tsx): `apps/web/components/ConversationView.tsx`
- [Chat display](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/components/chat/ChatView.tsx): `apps/web/components/chat/ChatView.tsx`
- [Participant panel](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/components/chat/ParticipantsPanel.tsx): `apps/web/components/chat/ParticipantsPanel.tsx`
- [Live progress](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/hooks/useConversationEvents.ts): `apps/web/hooks/useConversationEvents.ts`
- [Message loading](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/hooks/useMessages.ts): `apps/web/hooks/useMessages.ts`
- [API client](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/web/lib/api.ts): `apps/web/lib/api.ts`

### API

- [HTTP routes](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Conversation routes](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/routes/conversations.ts): `apps/api/src/routes/conversations.ts`
- [Event stream](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/routes/events.ts): `apps/api/src/routes/events.ts`
- [Message routes](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/routes/messages.ts): `apps/api/src/routes/messages.ts`
- [Media routes](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/routes/media.ts): `apps/api/src/routes/media.ts`
- [API serializers](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/api/src/serializers.ts): `apps/api/src/serializers.ts`

### Background processing

- [ZIP ingestion](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/ingest.ts): `apps/worker/src/ingest.ts`
- [Safe extraction](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/zip/safeExtract.ts): `apps/worker/src/zip/safeExtract.ts`
- [Conversation state](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/conversation.ts): `apps/worker/src/conversation.ts`
- [Finalization](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/finalize.ts): `apps/worker/src/finalize.ts`
- [Audio jobs](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/transcribe.ts): `apps/worker/src/transcribe.ts`
- [Audio pipeline](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/transcription/pipeline.ts): `apps/worker/src/transcription/pipeline.ts`
- [Audio conversion](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/audio/ffmpeg.ts): `apps/worker/src/audio/ffmpeg.ts`
- [Media hashing](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/media/hash.ts): `apps/worker/src/media/hash.ts`

### Chat and transcription

- [Chat parser](https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/core/src/parser/index.ts): `packages/core/src/parser/index.ts`
- [Attachment parsing](https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/core/src/parser/attachments.ts): `packages/core/src/parser/attachments.ts`
- [Date parsing](https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/core/src/parser/dates.ts): `packages/core/src/parser/dates.ts`
- [Format detection](https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/core/src/parser/patterns.ts): `packages/core/src/parser/patterns.ts`
- [Provider interface](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/transcription/provider.ts): `apps/worker/src/transcription/provider.ts`
- [OpenAI transcription](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/transcription/openai.ts): `apps/worker/src/transcription/openai.ts`
- [Mock transcription](https://github.com/brvieira/whatsapp-transcriber/blob/main/apps/worker/src/transcription/mock.ts): `apps/worker/src/transcription/mock.ts`

### Storage and queue

- [MongoDB](https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/db/src/schema.ts): `packages/db/src/schema.ts`
- [Redis job queue](https://github.com/brvieira/whatsapp-transcriber/blob/main/packages/queue/src/index.ts): `packages/queue/src/index.ts`
- **Local media files**

### Other components

- **Uploader**

## Connections

- Uploader → ZIP upload: uploads ZIP
- ZIP upload → API client: sends upload
- API client → Conversation routes: calls API
- Conversation routes → Redis job queue: enqueues ingest
- Conversation routes → MongoDB: stores upload state (evidence: `apps/api/src/routes/conversations.ts`)
- Conversation routes → Local media files: writes ZIP (evidence: `apps/api/src/routes/conversations.ts`)
- Redis job queue → ZIP ingestion: dispatches job
- ZIP ingestion → Safe extraction: extracts archive (evidence: `apps/worker/src/ingest.ts`)
- ZIP ingestion → Chat parser: parses chat (evidence: `apps/worker/src/ingest.ts`)
- Chat parser → Attachment parsing: classifies media (evidence: `packages/core/src/parser/index.ts`)
- Chat parser → Date parsing: interprets dates (evidence: `packages/core/src/parser/index.ts`)
- Chat parser → Format detection: detects formats (evidence: `packages/core/src/parser/index.ts`)
- ZIP ingestion → MongoDB: writes messages (evidence: `apps/worker/src/ingest.ts`)
- ZIP ingestion → Local media files: stores extracted media
- ZIP ingestion → Conversation state: updates status (evidence: `apps/worker/src/ingest.ts`)
- ZIP ingestion → Redis job queue: schedules audio jobs (evidence: `apps/worker/src/ingest.ts`)
- Audio jobs → Audio pipeline: processes audio
- Audio pipeline → Audio conversion: converts and splits (evidence: `apps/worker/src/transcription/pipeline.ts`)
- Audio pipeline → Provider interface: requests transcription (evidence: `apps/worker/src/transcription/pipeline.ts`)
- Provider interface → OpenAI transcription: uses provider
- Provider interface → Mock transcription: uses provider
- Audio jobs → MongoDB: stores transcripts
- ZIP ingestion → Media hashing: hashes media (evidence: `apps/worker/src/ingest.ts`)
- Finalization → MongoDB: saves final stats
- Redis job queue → Finalization: dispatches after audio
- API client → Event stream: opens SSE
- Event stream → MongoDB: watches progress (evidence: `apps/api/src/routes/events.ts`)
- Event stream → Live progress: streams updates
- API client → Message routes: requests messages
- Message routes → MongoDB: reads messages (evidence: `apps/api/src/routes/messages.ts`)
- Message routes → API serializers: formats responses (evidence: `apps/api/src/routes/messages.ts`)
- Conversation routes → API serializers: formats summaries (evidence: `apps/api/src/routes/conversations.ts`)
- API client → Media routes: requests media
- Media routes → Local media files: serves media
- Conversation pages → Message loading: loads conversation
- Conversation pages → Live progress: shows progress
- Conversation pages → Chat display: renders chat
- Chat display → Participant panel: shows participants
