# zoxt/vouch architecture

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

- Interactive diagram: https://gitdiagram.com/zoxt/vouch
- Repository: https://github.com/zoxt/vouch

## Overview

Vouch collects customer testimonials, processes media asynchronously, then makes completed testimonials searchable and publishable as embeds. Owners use the authenticated dashboard for campaigns, requests, library search, embed management, and billing; customers submit anonymously through public links; site visitors view captioned walls and players. The README documents the worker pipeline and integrations, while sampled source confirms search, embedding, and embed rendering details. Some domain-service wiring is unsampled, so those links are omitted where ownership is unclear.

Main entry points: [`src/queues`](https://github.com/zoxt/vouch/tree/main/src/queues) (Job queues), [`src/index.ts`](https://github.com/zoxt/vouch/blob/main/src/index.ts) (HTTP API), [`frontend/src/App.tsx`](https://github.com/zoxt/vouch/blob/main/frontend/src/App.tsx) (Dashboard), [`frontend/src/features/submission/pages`](https://github.com/zoxt/vouch/tree/main/frontend/src/features/submission/pages) (Public submission)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_dashboard["Dashboard<br/>[App.tsx]"]
  node_submission["Public submission"]
end

subgraph group_api["API and domain"]
  node_api_entry["HTTP API<br/>[index.ts]"]
  node_campaigns["Campaign management"]
  node_testimonial["Testimonial management"]
  node_auth["Authentication<br/>[auth.controller.ts]"]
  node_billing["Billing"]
end

subgraph group_processing["Media processing"]
  node_queues["Job queues"]
  node_media_worker["Media validation<br/>[media.worker.ts]"]
  node_transcription["Transcription and captions"]
  node_ai_analysis["AI analysis<br/>[ai.worker.ts]"]
  node_embedding_worker["Embedding worker"]
  node_s3[("Video storage<br/>[s3.ts]")]
end

subgraph group_delivery["Search and delivery"]
  node_database[("Postgres and pgvector<br/>[prisma.ts]")]
  node_embedding_service["Embedding service<br/>[main.py]"]
  node_search["Semantic search"]
  node_embed_delivery["Server-rendered embeds"]
end

node_owner(("Business owner"))
node_customer(("Testimonial customer"))
node_visitor(("Site visitor"))
node_paddle["Paddle"]
node_groq["Groq AI services"]

node_owner -->|"manages"| node_dashboard
node_customer -->|"submits"| node_submission
node_visitor -->|"views"| node_embed_delivery
node_dashboard -->|"calls API"| node_api_entry
node_submission -->|"confirms submission"| node_api_entry
node_api_entry -->|"dispatches"| node_campaigns
node_api_entry -->|"dispatches"| node_testimonial
node_api_entry -->|"dispatches"| node_auth
node_api_entry -->|"dispatches"| node_billing
node_campaigns -->|"issues upload URL"| node_s3
node_submission -->|"uploads directly"| node_s3
node_campaigns -->|"enqueues processing"| node_queues
node_queues -->|"dispatches jobs"| node_media_worker
node_media_worker -->|"reads media"| node_s3
node_media_worker -->|"queues transcription"| node_queues
node_queues -->|"dispatches jobs"| node_transcription
node_transcription -.->|"transcribes"| node_groq
node_transcription -->|"queues analysis"| node_queues
node_queues -->|"dispatches jobs"| node_ai_analysis
node_ai_analysis -.->|"analyzes transcript"| node_groq
node_ai_analysis -->|"queues embedding"| node_queues
node_queues -->|"dispatches jobs"| node_embedding_worker
node_embedding_worker -->|"reads transcript; writes vector"| node_database
node_embedding_worker -->|"requests embedding"| node_embedding_service
node_search -->|"embeds query"| node_embedding_service
node_search -->|"queries vectors"| node_database
node_dashboard -->|"searches library"| node_search
node_embed_delivery -->|"reads embed data"| node_database
node_embed_delivery -->|"serves wall and player"| node_visitor
node_billing -.->|"verifies billing events"| node_paddle

click node_dashboard "https://github.com/zoxt/vouch/blob/main/frontend/src/App.tsx"
click node_submission "https://github.com/zoxt/vouch/tree/main/frontend/src/features/submission/pages"
click node_api_entry "https://github.com/zoxt/vouch/blob/main/src/index.ts"
click node_campaigns "https://github.com/zoxt/vouch/blob/main/src/controllers/campaign.controller.ts"
click node_testimonial "https://github.com/zoxt/vouch/blob/main/src/controllers/testimonial.controller.ts"
click node_auth "https://github.com/zoxt/vouch/blob/main/src/controllers/auth.controller.ts"
click node_billing "https://github.com/zoxt/vouch/blob/main/src/controllers/subscription.controller.ts"
click node_queues "https://github.com/zoxt/vouch/tree/main/src/queues"
click node_media_worker "https://github.com/zoxt/vouch/blob/main/src/workers/media.worker.ts"
click node_transcription "https://github.com/zoxt/vouch/blob/main/src/workers/transcription.worker.ts"
click node_ai_analysis "https://github.com/zoxt/vouch/blob/main/src/workers/ai.worker.ts"
click node_embedding_worker "https://github.com/zoxt/vouch/blob/main/src/workers/embedding.worker.ts"
click node_s3 "https://github.com/zoxt/vouch/blob/main/src/config/s3.ts"
click node_database "https://github.com/zoxt/vouch/blob/main/src/config/prisma.ts"
click node_embedding_service "https://github.com/zoxt/vouch/blob/main/embedding-service/main.py"
click node_search "https://github.com/zoxt/vouch/blob/main/src/controllers/search.controller.ts"
click node_embed_delivery "https://github.com/zoxt/vouch/blob/main/src/controllers/embed.controller.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_dashboard,node_submission toneBlue
class node_api_entry,node_campaigns,node_testimonial,node_auth,node_billing toneAmber
class node_queues,node_media_worker,node_transcription,node_ai_analysis,node_embedding_worker,node_s3 toneMint
class node_database,node_embedding_service,node_search,node_embed_delivery toneRose
class node_owner,node_customer,node_visitor,node_paddle,node_groq toneIndigo
```

## Components

### User surfaces

- [Dashboard](https://github.com/zoxt/vouch/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Public submission](https://github.com/zoxt/vouch/tree/main/frontend/src/features/submission/pages): `frontend/src/features/submission/pages`

### API and domain

- [HTTP API](https://github.com/zoxt/vouch/blob/main/src/index.ts): `src/index.ts`
- [Campaign management](https://github.com/zoxt/vouch/blob/main/src/controllers/campaign.controller.ts): `src/controllers/campaign.controller.ts`
- [Testimonial management](https://github.com/zoxt/vouch/blob/main/src/controllers/testimonial.controller.ts): `src/controllers/testimonial.controller.ts`
- [Authentication](https://github.com/zoxt/vouch/blob/main/src/controllers/auth.controller.ts): `src/controllers/auth.controller.ts`
- [Billing](https://github.com/zoxt/vouch/blob/main/src/controllers/subscription.controller.ts): `src/controllers/subscription.controller.ts`

### Media processing

- [Job queues](https://github.com/zoxt/vouch/tree/main/src/queues): `src/queues`
- [Media validation](https://github.com/zoxt/vouch/blob/main/src/workers/media.worker.ts): `src/workers/media.worker.ts`
- [Transcription and captions](https://github.com/zoxt/vouch/blob/main/src/workers/transcription.worker.ts): `src/workers/transcription.worker.ts`
- [AI analysis](https://github.com/zoxt/vouch/blob/main/src/workers/ai.worker.ts): `src/workers/ai.worker.ts`
- [Embedding worker](https://github.com/zoxt/vouch/blob/main/src/workers/embedding.worker.ts): `src/workers/embedding.worker.ts`
- [Video storage](https://github.com/zoxt/vouch/blob/main/src/config/s3.ts): `src/config/s3.ts`

### Search and delivery

- [Postgres and pgvector](https://github.com/zoxt/vouch/blob/main/src/config/prisma.ts): `src/config/prisma.ts`
- [Embedding service](https://github.com/zoxt/vouch/blob/main/embedding-service/main.py): `embedding-service/main.py`
- [Semantic search](https://github.com/zoxt/vouch/blob/main/src/controllers/search.controller.ts): `src/controllers/search.controller.ts`
- [Server-rendered embeds](https://github.com/zoxt/vouch/blob/main/src/controllers/embed.controller.ts): `src/controllers/embed.controller.ts`

### Other components

- **Business owner**
- **Testimonial customer**
- **Site visitor**
- **Paddle**
- **Groq AI services**

## Connections

- Business owner → Dashboard: manages
- Testimonial customer → Public submission: submits
- Site visitor → Server-rendered embeds: views
- Dashboard → HTTP API: calls API
- Public submission → HTTP API: confirms submission
- HTTP API → Campaign management: dispatches
- HTTP API → Testimonial management: dispatches
- HTTP API → Authentication: dispatches
- HTTP API → Billing: dispatches
- Campaign management → Video storage: issues upload URL
- Public submission → Video storage: uploads directly
- Campaign management → Job queues: enqueues processing
- Job queues → Media validation: dispatches jobs
- Media validation → Video storage: reads media
- Media validation → Job queues: queues transcription
- Job queues → Transcription and captions: dispatches jobs
- Transcription and captions → Groq AI services: transcribes
- Transcription and captions → Job queues: queues analysis
- Job queues → AI analysis: dispatches jobs
- AI analysis → Groq AI services: analyzes transcript
- AI analysis → Job queues: queues embedding
- Job queues → Embedding worker: dispatches jobs
- Embedding worker → Postgres and pgvector: reads transcript; writes vector
- Embedding worker → Embedding service: requests embedding
- Semantic search → Embedding service: embeds query
- Semantic search → Postgres and pgvector: queries vectors
- Dashboard → Semantic search: searches library
- Server-rendered embeds → Postgres and pgvector: reads embed data
- Server-rendered embeds → Site visitor: serves wall and player
- Billing → Paddle: verifies billing events