# akazdayo/discord-meeting-note architecture

> Architecture diagram of the GitHub repository akazdayo/discord-meeting-note, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akazdayo/discord-meeting-note
- Repository: https://github.com/akazdayo/discord-meeting-note

## Overview

**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: [`apps/bot/src/index.ts`](https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/index.ts) (Bot), [`packages/transcription/core/src/index.ts`](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/core/src/index.ts) (Transcribe Core), [`packages/llm/core/src/index.ts`](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/llm/core/src/index.ts) (LLM Core), [`apps/bot/src/pipeline.ts`](https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/pipeline.ts) (Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_apps["Apps"]
  node_app_bot["Bot<br/>discord runtime<br/>[index.ts]"]
  node_bot_commands["Commands<br/>control plane<br/>[index.ts]"]
  node_bot_voice["Voice Manager<br/>voice I/O<br/>[voice-manager.ts]"]
  node_bot_pipeline["Pipeline<br/>async orchestration<br/>[pipeline.ts]"]
  node_bot_cleanup["Cleanup<br/>retention job<br/>[cleanup.ts]"]
end

subgraph group_group_data["Data"]
  node_db_service[("Database<br/>sqlite service<br/>[service.ts]")]
  node_db_schema["Schema<br/>[schema.ts]"]
end

subgraph group_group_transcription["Transcription"]
  node_trans_core["Transcribe Core<br/>provider interface<br/>[index.ts]"]
  node_trans_mlx["MLX Whisper<br/>local transcription<br/>[index.ts]"]
  node_trans_whisper["Whisper<br/>local transcription<br/>[index.ts]"]
  node_trans_assembly["AssemblyAI<br/>hosted transcription<br/>[index.ts]"]
  node_trans_google["Google STT<br/>hosted transcription<br/>[index.ts]"]
end

subgraph group_group_llm["LLM"]
  node_llm_core["LLM Core<br/>model interface<br/>[index.ts]"]
  node_llm_openai["OpenAI<br/>summary provider<br/>[index.ts]"]
  node_llm_gemini["Gemini<br/>summary provider<br/>[index.ts]"]
  node_llm_ollama["Ollama<br/>summary provider<br/>[index.ts]"]
end

subgraph group_group_shared["Shared"]
  node_shared_types["Types<br/>contracts<br/>[index.ts]"]
  node_shared_errors["Errors<br/>contracts<br/>[index.ts]"]
end

subgraph group_group_external["External"]
  node_discord(("Discord<br/>event source"))
  node_ffmpeg(("ffmpeg<br/>audio tool"))
  node_openai_api(("OpenAI API<br/>external service"))
end

node_discord -->|"events"| node_app_bot
node_app_bot -->|"routes"| node_bot_commands
node_app_bot -->|"captures"| node_bot_voice
node_bot_commands -->|"starts"| node_bot_pipeline
node_bot_voice -->|"encodes"| node_ffmpeg
node_bot_voice -->|"stores session"| node_db_service
node_bot_pipeline -->|"transcribes via"| node_trans_core
node_trans_core -->|"default impl"| node_trans_mlx
node_trans_core -->|"alt impl"| node_trans_whisper
node_trans_core -->|"alt impl"| node_trans_assembly
node_trans_core -->|"alt impl"| node_trans_google
node_bot_pipeline -->|"summarizes via"| node_llm_core
node_llm_core -->|"default impl"| node_llm_openai
node_llm_core -->|"alt impl"| node_llm_gemini
node_llm_core -->|"alt impl"| node_llm_ollama
node_llm_openai -->|"calls"| node_openai_api
node_bot_pipeline -->|"persists results"| node_db_service
node_db_service -->|"uses"| node_db_schema
node_app_bot -->|"runs"| node_bot_cleanup
node_app_bot -->|"shares types"| node_shared_types
node_app_bot -->|"shares errors"| node_shared_errors
node_db_service -->|"shares types"| node_shared_types
node_trans_core -->|"throws"| node_shared_errors
node_llm_core -->|"throws"| node_shared_errors

click node_app_bot "https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/index.ts"
click node_bot_commands "https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/commands/index.ts"
click node_bot_voice "https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/voice-manager.ts"
click node_bot_pipeline "https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/pipeline.ts"
click node_bot_cleanup "https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/cleanup.ts"
click node_db_service "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/database/src/service.ts"
click node_db_schema "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/database/src/schema.ts"
click node_shared_types "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/shared/types/src/index.ts"
click node_shared_errors "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/shared/errors/src/index.ts"
click node_trans_core "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/core/src/index.ts"
click node_trans_mlx "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/mlx-whisper/src/index.ts"
click node_trans_whisper "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/whisper/src/index.ts"
click node_trans_assembly "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/assembly-ai/src/index.ts"
click node_trans_google "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/google-stt/src/index.ts"
click node_llm_core "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/llm/core/src/index.ts"
click node_llm_openai "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/llm/openai/src/index.ts"
click node_llm_gemini "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/llm/gemini/src/index.ts"
click node_llm_ollama "https://github.com/akazdayo/discord-meeting-note/blob/main/packages/llm/ollama/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_app_bot,node_bot_commands,node_bot_voice,node_bot_pipeline,node_bot_cleanup toneBlue
class node_db_service,node_db_schema toneAmber
class node_trans_core,node_trans_mlx,node_trans_whisper,node_trans_assembly,node_trans_google toneMint
class node_llm_core,node_llm_openai,node_llm_gemini,node_llm_ollama toneRose
class node_shared_types,node_shared_errors toneIndigo
class node_discord,node_ffmpeg,node_openai_api toneTeal
```

## Components

### Apps

Deployable runtime service

- [Bot](https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/index.ts): discord runtime · Deployable Discord service that handles commands, voice capture, orchestration, and cleanup · `apps/bot/src/index.ts`
- [Commands](https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/commands/index.ts): control plane · Slash command entrypoints for record, export, and summarize flows · `apps/bot/src/commands/index.ts`
- [Voice Manager](https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/voice-manager.ts): voice I/O · Connects to Discord voice channels and records meeting audio · `apps/bot/src/voice-manager.ts`
- [Pipeline](https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/pipeline.ts): async orchestration · Post-recording processing flow that drives transcription and summarization · `apps/bot/src/pipeline.ts`
- [Cleanup](https://github.com/akazdayo/discord-meeting-note/blob/main/apps/bot/src/cleanup.ts): retention job · Removes expired local artifacts and keeps storage bounded · `apps/bot/src/cleanup.ts`

### Data

Persistence and artifact storage

- [Database](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/database/src/service.ts): sqlite service · Drizzle-backed persistence for sessions, transcripts, and summaries · `packages/database/src/service.ts`
- [Schema](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/database/src/schema.ts): drizzle schema · SQLite table definitions and durable record shape · `packages/database/src/schema.ts`

### Transcription

Speech-to-text adapters

- [Transcribe Core](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/core/src/index.ts): provider interface · Abstract transcription contract used by the bot · `packages/transcription/core/src/index.ts`
- [MLX Whisper](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/mlx-whisper/src/index.ts): local transcription · Default local Whisper-based transcription path for Apple Silicon · `packages/transcription/mlx-whisper/src/index.ts`
- [Whisper](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/whisper/src/index.ts): local transcription · Whisper transcription adapter · `packages/transcription/whisper/src/index.ts`
- [AssemblyAI](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/assembly-ai/src/index.ts): hosted transcription · AssemblyAI transcription adapter · `packages/transcription/assembly-ai/src/index.ts`
- [Google STT](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/transcription/google-stt/src/index.ts): hosted transcription · Google speech-to-text adapter · `packages/transcription/google-stt/src/index.ts`

### LLM

Summarization interfaces and providers

- [LLM Core](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/llm/core/src/index.ts): model interface · Abstract summarization contract · `packages/llm/core/src/index.ts`
- [OpenAI](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/llm/openai/src/index.ts): summary provider · OpenAI-backed summarization implementation · `packages/llm/openai/src/index.ts`
- [Gemini](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/llm/gemini/src/index.ts): summary provider · Gemini-backed summarization implementation · `packages/llm/gemini/src/index.ts`
- [Ollama](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/llm/ollama/src/index.ts): summary provider · Local Ollama-backed summarization implementation · `packages/llm/ollama/src/index.ts`

### Shared

Cross-package contracts

- [Types](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/shared/types/src/index.ts): contracts · Shared cross-package data types and session models · `packages/shared/types/src/index.ts`
- [Errors](https://github.com/akazdayo/discord-meeting-note/blob/main/packages/shared/errors/src/index.ts): contracts · Shared custom error classes across packages · `packages/shared/errors/src/index.ts`

### External

Outside systems and runtime tools

- **Discord**: event source · Chat and voice platform for commands and meeting capture
- **ffmpeg**: audio tool · Local media processing dependency for audio handling
- **OpenAI API**: external service · Remote model API used for meeting summaries

## Connections

- 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
