How akazdayo/discord-meeting-note works
1. Repository shape
This is a Turborepo-based TypeScript monorepo for a self-hosted Discord meeting note bot. The architecture is split into one runtime application and several reusable packages, with the app depending on the packages rather than containing the core business logic itself.
2. Runtime boundary: apps/bot
apps/bot is the only deployable service. It owns Discord connectivity, slash command handling, voice-channel interaction, and orchestration of the recording/transcription/summarization flow. The bot is intentionally thin and acts as the I/O boundary into the rest of the system.
3. Discord command entrypoints
The main user-facing flows are /record start, /record stop, /export audio|transcript|summary, and /summarize. These commands trigger the internal pipeline, read from persisted session data, or send stored artifacts back to Discord. The command layer is the primary control plane for the system.
4. Voice capture and file handling
The bot connects to Discord voice channels, records audio, and stores the raw result as .ogg files under a data/audio/ directory. Audio retention is time-bound: the README states audio is automatically deleted after 7 days. There is also a cleanup path in apps/bot/src/cleanup.ts, which suggests the app periodically removes old artifacts and keeps local storage bounded.
5. Processing pipeline
apps/bot/src/pipeline.ts and the associated tests indicate a distinct orchestration pipeline for post-processing. The pipeline likely takes a recorded session, invokes transcription, then invokes summarization, and finally updates persistence/notifications. This is the main asynchronous boundary: recording stops synchronously, while transcription and summarization continue in the background.
6. Persistence layer: packages/database
packages/database is the durable state layer, implemented with SQLite via Drizzle ORM. It stores session metadata plus transcription and summary results, and the README’s db.sqlite path confirms the database lives on local disk inside the configured DATA_DIR. The bot app depends on this package for all session lifecycle reads/writes rather than embedding SQL in the app.
7. Transcription subsystem
packages/transcription/core defines the transcription abstraction, while concrete implementations live in assembly-ai, google-stt, whisper, and mlx-whisper. This is a clean plugin boundary: the bot can swap between local CLI-based transcription and hosted speech-to-text providers without changing the app layer. The README explicitly documents mlx-whisper as the default local CLI path for Apple Silicon.
8. LLM summarization subsystem
packages/llm/core defines the model interface for summarization, and packages/llm/openai provides the concrete implementation used by the bot. The README shows OpenAI is required for summaries, with OPENAI_MODEL configurable. This keeps prompt/model integration outside the bot and makes the summarization backend replaceable in principle.
9. Shared contracts and errors
packages/shared/types and packages/shared/errors centralize cross-package types and custom error classes. These packages act as the contract layer between the bot, database, transcription, and LLM packages, reducing coupling and making the monorepo boundaries explicit.
10. External dependencies that shape the architecture
Discord is the event source and delivery channel, OpenAI is the summarization service, and local CLI tools (ffmpeg, mlx_whisper, or other Whisper variants) are part of the processing runtime. The system is therefore hybrid: online for control and summarization, but local/self-hosted for recording and most transcription options.
11. Data flow summary
A typical flow is: Discord slash command → bot records voice/audio → audio stored on disk → session state written to SQLite → transcription provider runs on the audio file → summary provider runs on the transcript → results persisted → bot posts completion/exports back to Discord. This is the central architecture path to reflect in a diagram.
12. Operational model
The project is designed to run locally or on a self-hosted machine, with a single data directory containing both durable state and generated artifacts. Build/test tooling is workspace-based (pnpm, turbo, mise), but it does not materially change the runtime architecture; the important operational constraint is that the host must provide Discord credentials, OpenAI access, ffmpeg, and whichever transcription backend is selected.
Main entry points: src/index.ts Bot · src/index.ts Transcribe Core · src/index.ts LLM Core · pipeline.ts Pipeline
Components 21
Apps
Deployable runtime service
- Bot · Deployable Discord service that handles commands, voice capture, orchestration, and cleanup
apps/bot/src/index.ts - Commands · Slash command entrypoints for record, export, and summarize flows
apps/bot/src/commands/index.ts - Voice Manager · Connects to Discord voice channels and records meeting audio
apps/bot/src/voice-manager.ts - Pipeline · Post-recording processing flow that drives transcription and summarization
apps/bot/src/pipeline.ts - Cleanup · Removes expired local artifacts and keeps storage bounded
apps/bot/src/cleanup.ts
Data
Persistence and artifact storage
Transcription
Speech-to-text adapters
- Transcribe Core · Abstract transcription contract used by the bot
packages/transcription/core/src/index.ts - MLX Whisper · Default local Whisper-based transcription path for Apple Silicon
packages/transcription/mlx-whisper/src/index.ts - Whisper · Whisper transcription adapter
packages/transcription/whisper/src/index.ts - AssemblyAI · AssemblyAI transcription adapter
packages/transcription/assembly-ai/src/index.ts - Google STT · Google speech-to-text adapter
packages/transcription/google-stt/src/index.ts
LLM
Summarization interfaces and providers
- LLM Core · Abstract summarization contract
packages/llm/core/src/index.ts - OpenAI · OpenAI-backed summarization implementation
packages/llm/openai/src/index.ts - Gemini · Gemini-backed summarization implementation
packages/llm/gemini/src/index.ts - Ollama · Local Ollama-backed summarization implementation
packages/llm/ollama/src/index.ts
Shared
Cross-package contracts
External
Outside systems and runtime tools
- Discord · Chat and voice platform for commands and meeting capture
- ffmpeg · Local media processing dependency for audio handling
- OpenAI API · Remote model API used for meeting summaries
Connections 24
- Discord → Bot: events · Discord delivers slash commands and voice session events to the bot
- Bot → Commands: routes · Bot dispatches incoming commands to the command layer
- Bot → Voice Manager: captures · Bot uses the voice manager to join channels and record audio
- Commands → Pipeline: starts · Record stop and summarize commands trigger processing
- Voice Manager → ffmpeg: encodes · Recorded audio depends on local media tooling
- Voice Manager → Database: stores session · Recording session state is persisted locally
- Pipeline → Transcribe Core: transcribes via · Pipeline invokes the transcription abstraction
- Transcribe Core → MLX Whisper: default impl · Local MLX Whisper is the default transcription path
- Transcribe Core → Whisper: alt impl · Whisper adapter provides another local transcription path
- Transcribe Core → AssemblyAI: alt impl · AssemblyAI adapter provides hosted transcription
- Transcribe Core → Google STT: alt impl · Google STT adapter provides hosted transcription
- Pipeline → LLM Core: summarizes via · Pipeline invokes the summarization abstraction after transcription
- LLM Core → OpenAI: default impl · OpenAI implementation is the primary summary backend
- LLM Core → Gemini: alt impl · Gemini adapter provides another summary backend
- LLM Core → Ollama: alt impl · Ollama adapter provides a local summary backend
- OpenAI → OpenAI API: calls · OpenAI provider sends transcript text to the external API
- Pipeline → Database: persists results · Transcripts and summaries are written back to SQLite
- Database → Schema: uses · Service is implemented from the shared schema
- Bot → Cleanup: runs · Bot schedules cleanup of expired artifacts
- Bot → Types: shares types · Runtime code uses shared contracts for sessions and results
- Bot → Errors: shares errors · Runtime code uses common error classes
- Database → Types: shares types · Persistence layer uses shared data contracts
- Transcribe Core → Errors: throws · Transcription adapters share common error types
- LLM Core → Errors: throws · LLM adapters share common error types