# voxgig/podmind architecture

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

- Interactive diagram: https://gitdiagram.com/voxgig/podmind
- Repository: https://github.com/voxgig/podmind

## Overview

Podmind is a podcast RAG application: podcast feeds and audio are ingested, transcripts and chunks are prepared for retrieval, and users ask questions through a web app or embeddable widget. The README documents AWS-backed serverless deployment and the local-monolith mode; the sampled ingestion code explicitly dispatches episode processing, and the widget explicitly posts chat queries. Many backend service-to-service and storage calls were not sampled, so those relationships are omitted or marked unverified rather than presented as observed calls.

Main entry points: [`backend/src/srv/ingest/process_episode.ts`](https://github.com/voxgig/podmind/blob/main/backend/src/srv/ingest/process_episode.ts) (Episode processing), [`frontend/src/App.tsx`](https://github.com/voxgig/podmind/blob/main/frontend/src/App.tsx) (Web application), [`backend/src/srv/chat/chat_query.ts`](https://github.com/voxgig/podmind/blob/main/backend/src/srv/chat/chat_query.ts) (Chat query), [`backend/src/srv/ingest/ingest_podcast.ts`](https://github.com/voxgig/podmind/blob/main/backend/src/srv/ingest/ingest_podcast.ts) (Feed ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Podcast ingestion"]
  node_feed_ingest["Feed ingestion<br/>[ingest_podcast.ts]"]
  node_episode_process["Episode processing<br/>[process_episode.ts]"]
  node_podcast_process["Podcast processing<br/>[PodcastProcess.ts]"]
  node_transcription["Audio transcription"]
end

subgraph group_retrieval["RAG processing"]
  node_chunking["Transcript chunking"]
  node_chunk_handling["Transcript handling"]
  node_embedding["Embedding storage<br/>[store_embed.ts]"]
  node_chat_query["Chat query<br/>[chat_query.ts]"]
  node_prompting["Prompt assembly<br/>[build_prompt.ts]"]
end

subgraph group_api["Backend services"]
  node_widget_query["Widget query API<br/>[web_chat_query.ts]"]
  node_auth["Authentication<br/>[auth-srv.ts]"]
  node_entity["Entity management<br/>[entity-srv.ts]"]
  node_user["User services<br/>[user-srv.ts]"]
  node_prompt_service["Prompt services<br/>[prompt-srv.ts]"]
  node_monitor["Monitoring<br/>[monitor-srv.ts]"]
end

subgraph group_clients["User interfaces"]
  node_web_app["Web application<br/>[App.tsx]"]
  node_web_setup["Browser client setup<br/>[setup.ts]"]
  node_public_page["Public auth page<br/>[Public.tsx]"]
  node_private_page["Private views<br/>[Private.tsx]"]
  node_search_view["Search view<br/>[Search.tsx]"]
  node_ask_widget["Embeddable chat widget"]
end

subgraph group_platform["Runtime platform"]
  node_lambda_runtime["Lambda runtime<br/>[lambda.ts]"]
  node_aws_services[("AWS services")]
  node_bedrock["AWS Bedrock LLM"]
  node_deepgram["Deepgram"]
end

node_publisher(("Podcast publisher"))

node_publisher -->|"submits feed"| node_feed_ingest
node_feed_ingest -->|"dispatches episode"| node_episode_process
node_episode_process -.->|"delegates processing"| node_podcast_process
node_episode_process -.->|"requests transcription"| node_transcription
node_transcription -.->|"transcribes audio"| node_deepgram
node_episode_process -.->|"prepares transcript"| node_chunking
node_chunking -.->|"handles chunks"| node_chunk_handling
node_chunk_handling -.->|"creates embeddings"| node_embedding
node_embedding -.->|"stores vectors"| node_aws_services
node_chat_query -.->|"builds prompt"| node_prompting
node_chat_query -.->|"queries model"| node_bedrock
node_ask_widget -.->|"posts query"| node_widget_query
node_widget_query -.->|"dispatches query"| node_chat_query
node_web_app -->|"initializes client"| node_web_setup
node_web_app -->|"routes public"| node_public_page
node_web_app -->|"routes private"| node_private_page
node_private_page -->|"renders search"| node_search_view
node_web_setup -.->|"requests auth"| node_auth
node_lambda_runtime -.->|"uses services"| node_aws_services

click node_feed_ingest "https://github.com/voxgig/podmind/blob/main/backend/src/srv/ingest/ingest_podcast.ts"
click node_episode_process "https://github.com/voxgig/podmind/blob/main/backend/src/srv/ingest/process_episode.ts"
click node_podcast_process "https://github.com/voxgig/podmind/blob/main/backend/src/concern/PodcastProcess/PodcastProcess.ts"
click node_transcription "https://github.com/voxgig/podmind/blob/main/backend/src/srv/audio/transcribe_episode.ts"
click node_chunking "https://github.com/voxgig/podmind/blob/main/backend/src/srv/chunk/chunk_transcript.ts"
click node_chunk_handling "https://github.com/voxgig/podmind/blob/main/backend/src/srv/chunk/handle_transcript.ts"
click node_embedding "https://github.com/voxgig/podmind/blob/main/backend/src/srv/embed/store_embed.ts"
click node_chat_query "https://github.com/voxgig/podmind/blob/main/backend/src/srv/chat/chat_query.ts"
click node_prompting "https://github.com/voxgig/podmind/blob/main/backend/src/srv/prompt/build_prompt.ts"
click node_widget_query "https://github.com/voxgig/podmind/blob/main/backend/src/srv/widget/web_chat_query.ts"
click node_auth "https://github.com/voxgig/podmind/blob/main/backend/src/srv/auth/auth-srv.ts"
click node_entity "https://github.com/voxgig/podmind/blob/main/backend/src/srv/entity/entity-srv.ts"
click node_user "https://github.com/voxgig/podmind/blob/main/backend/src/srv/user/user-srv.ts"
click node_prompt_service "https://github.com/voxgig/podmind/blob/main/backend/src/srv/prompt/prompt-srv.ts"
click node_monitor "https://github.com/voxgig/podmind/blob/main/backend/src/srv/monitor/monitor-srv.ts"
click node_web_app "https://github.com/voxgig/podmind/blob/main/frontend/src/App.tsx"
click node_web_setup "https://github.com/voxgig/podmind/blob/main/frontend/src/setup.ts"
click node_public_page "https://github.com/voxgig/podmind/blob/main/frontend/src/public/Public.tsx"
click node_private_page "https://github.com/voxgig/podmind/blob/main/frontend/src/private/Private.tsx"
click node_search_view "https://github.com/voxgig/podmind/blob/main/frontend/src/private/Search.tsx"
click node_ask_widget "https://github.com/voxgig/podmind/blob/main/widget/ask-island/src/voxgig-podmind-ask.island.tsx"
click node_lambda_runtime "https://github.com/voxgig/podmind/blob/main/backend/src/env/lambda/lambda.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_feed_ingest,node_episode_process,node_podcast_process,node_transcription toneBlue
class node_chunking,node_chunk_handling,node_embedding,node_chat_query,node_prompting toneAmber
class node_widget_query,node_auth,node_entity,node_user,node_prompt_service,node_monitor toneMint
class node_web_app,node_web_setup,node_public_page,node_private_page,node_search_view,node_ask_widget toneRose
class node_lambda_runtime,node_aws_services,node_bedrock,node_deepgram,node_publisher toneIndigo
```

## Components

### Podcast ingestion

- [Feed ingestion](https://github.com/voxgig/podmind/blob/main/backend/src/srv/ingest/ingest_podcast.ts): `backend/src/srv/ingest/ingest_podcast.ts`
- [Episode processing](https://github.com/voxgig/podmind/blob/main/backend/src/srv/ingest/process_episode.ts): `backend/src/srv/ingest/process_episode.ts`
- [Podcast processing](https://github.com/voxgig/podmind/blob/main/backend/src/concern/PodcastProcess/PodcastProcess.ts): `backend/src/concern/PodcastProcess/PodcastProcess.ts`
- [Audio transcription](https://github.com/voxgig/podmind/blob/main/backend/src/srv/audio/transcribe_episode.ts): `backend/src/srv/audio/transcribe_episode.ts`

### RAG processing

- [Transcript chunking](https://github.com/voxgig/podmind/blob/main/backend/src/srv/chunk/chunk_transcript.ts): `backend/src/srv/chunk/chunk_transcript.ts`
- [Transcript handling](https://github.com/voxgig/podmind/blob/main/backend/src/srv/chunk/handle_transcript.ts): `backend/src/srv/chunk/handle_transcript.ts`
- [Embedding storage](https://github.com/voxgig/podmind/blob/main/backend/src/srv/embed/store_embed.ts): `backend/src/srv/embed/store_embed.ts`
- [Chat query](https://github.com/voxgig/podmind/blob/main/backend/src/srv/chat/chat_query.ts): `backend/src/srv/chat/chat_query.ts`
- [Prompt assembly](https://github.com/voxgig/podmind/blob/main/backend/src/srv/prompt/build_prompt.ts): `backend/src/srv/prompt/build_prompt.ts`

### Backend services

- [Widget query API](https://github.com/voxgig/podmind/blob/main/backend/src/srv/widget/web_chat_query.ts): `backend/src/srv/widget/web_chat_query.ts`
- [Authentication](https://github.com/voxgig/podmind/blob/main/backend/src/srv/auth/auth-srv.ts): `backend/src/srv/auth/auth-srv.ts`
- [Entity management](https://github.com/voxgig/podmind/blob/main/backend/src/srv/entity/entity-srv.ts): `backend/src/srv/entity/entity-srv.ts`
- [User services](https://github.com/voxgig/podmind/blob/main/backend/src/srv/user/user-srv.ts): `backend/src/srv/user/user-srv.ts`
- [Prompt services](https://github.com/voxgig/podmind/blob/main/backend/src/srv/prompt/prompt-srv.ts): `backend/src/srv/prompt/prompt-srv.ts`
- [Monitoring](https://github.com/voxgig/podmind/blob/main/backend/src/srv/monitor/monitor-srv.ts): `backend/src/srv/monitor/monitor-srv.ts`

### User interfaces

- [Web application](https://github.com/voxgig/podmind/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Browser client setup](https://github.com/voxgig/podmind/blob/main/frontend/src/setup.ts): `frontend/src/setup.ts`
- [Public auth page](https://github.com/voxgig/podmind/blob/main/frontend/src/public/Public.tsx): `frontend/src/public/Public.tsx`
- [Private views](https://github.com/voxgig/podmind/blob/main/frontend/src/private/Private.tsx): `frontend/src/private/Private.tsx`
- [Search view](https://github.com/voxgig/podmind/blob/main/frontend/src/private/Search.tsx): `frontend/src/private/Search.tsx`
- [Embeddable chat widget](https://github.com/voxgig/podmind/blob/main/widget/ask-island/src/voxgig-podmind-ask.island.tsx): `widget/ask-island/src/voxgig-podmind-ask.island.tsx`

### Runtime platform

- [Lambda runtime](https://github.com/voxgig/podmind/blob/main/backend/src/env/lambda/lambda.ts): `backend/src/env/lambda/lambda.ts`
- **AWS services**
- **AWS Bedrock LLM**
- **Deepgram**

### Other components

- **Podcast publisher**

## Connections

- Podcast publisher → Feed ingestion: submits feed
- Feed ingestion → Episode processing: dispatches episode (evidence: `backend/src/srv/ingest/ingest_podcast.ts`)
- Episode processing → Podcast processing: delegates processing
- Episode processing → Audio transcription: requests transcription
- Audio transcription → Deepgram: transcribes audio
- Episode processing → Transcript chunking: prepares transcript
- Transcript chunking → Transcript handling: handles chunks
- Transcript handling → Embedding storage: creates embeddings
- Embedding storage → AWS services: stores vectors
- Chat query → Prompt assembly: builds prompt
- Chat query → AWS Bedrock LLM: queries model
- Embeddable chat widget → Widget query API: posts query
- Widget query API → Chat query: dispatches query
- Web application → Browser client setup: initializes client (evidence: `frontend/src/App.tsx`)
- Web application → Public auth page: routes public (evidence: `frontend/src/App.tsx`)
- Web application → Private views: routes private (evidence: `frontend/src/App.tsx`)
- Private views → Search view: renders search (evidence: `frontend/src/private/Private.tsx`)
- Browser client setup → Authentication: requests auth (evidence: `frontend/src/setup.ts`)
- Lambda runtime → AWS services: uses services
