# itz-snj/prism architecture

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

- Interactive diagram: https://gitdiagram.com/itz-snj/prism
- Repository: https://github.com/itz-snj/prism

## Overview

Prism is a YouTube learning workspace: users ingest videos, follow background processing, then chat with transcript content and generate/submit quizzes. The backend also provides video/search and API-key management; the frontend exposes dashboard, workspace, and settings views. Edges follow shown calls/import references or README-documented flows. The worker’s detailed implementation and most frontend page-to-API calls were not excerpted, so those relationships are shown only where documentation supports them or are omitted.

Main entry points: [`backend/prisma/prisma.service.ts`](https://github.com/itz-snj/prism/blob/main/backend/prisma/prisma.service.ts) (PostgreSQL with pgvector), [`frontend/src/App.tsx`](https://github.com/itz-snj/prism/blob/main/frontend/src/App.tsx) (Web application), [`backend/src/search/search.service.ts`](https://github.com/itz-snj/prism/blob/main/backend/src/search/search.service.ts) (Vector search), [`backend/src/ingestion/ingestion.processor.ts`](https://github.com/itz-snj/prism/blob/main/backend/src/ingestion/ingestion.processor.ts) (Transcript worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Learning workspace"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_workspace["Video workspace<br/>[Workspace.tsx]"]
  node_settings["Settings<br/>[Settings.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_identity["Identity and keys"]
  node_auth_guard["Clerk auth guard"]
  node_auth_service["User sync<br/>[auth.service.ts]"]
  node_key_api["API key routes"]
  node_key_service["Encrypted API keys"]
end

subgraph group_ingestion["Video ingestion"]
  node_ingest_api["Ingestion routes"]
  node_ingest_service["Ingestion queue"]
  node_worker["Transcript worker"]
end

subgraph group_study["Study features"]
  node_chat_api["Chat routes<br/>[chat.controller.ts]"]
  node_chat_service["RAG chat<br/>[chat.service.ts]"]
  node_search_api["Search routes"]
  node_search_service["Vector search<br/>[search.service.ts]"]
  node_quiz_api["Quiz routes<br/>[quiz.controller.ts]"]
  node_quiz_service["Quiz generation and results<br/>[quiz.service.ts]"]
  node_video_service["Video access<br/>[video.service.ts]"]
end

subgraph group_persistence["Persistence and services"]
  node_database[("PostgreSQL with pgvector<br/>[prisma.service.ts]")]
  node_redis["Redis and BullMQ"]
  node_gemini["Google Gemini"]
  node_youtube["YouTube captions"]
  node_clerk["Clerk identity"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_dashboard
node_webapp -->|"routes to"| node_workspace
node_webapp -->|"routes to"| node_settings
node_webapp -->|"sets up auth"| node_api_client
node_learner -->|"submits URL"| node_ingest_api
node_ingest_api -->|"queues job"| node_ingest_service
node_ingest_service -->|"adds job"| node_redis
node_redis -->|"dispatches job"| node_worker
node_worker -->|"fetches captions"| node_youtube
node_worker -->|"embeds chunks"| node_gemini
node_worker -->|"stores chunks"| node_database
node_ingest_api -->|"streams progress"| node_learner
node_learner -->|"asks question"| node_chat_api
node_chat_api -->|"delegates"| node_chat_service
node_chat_service -->|"retrieves context"| node_search_service
node_search_service -->|"gets key"| node_key_service
node_search_service -->|"embeds query"| node_gemini
node_search_service -->|"searches vectors"| node_database
node_chat_service -->|"generates answer"| node_gemini
node_learner -->|"requests quiz"| node_quiz_api
node_quiz_api -->|"delegates"| node_quiz_service
node_quiz_service -->|"reads and saves"| node_database
node_quiz_service -->|"gets key"| node_key_service
node_learner -->|"manages keys"| node_key_api
node_key_api -->|"delegates"| node_key_service
node_key_service -->|"stores encrypted keys"| node_database
node_auth_guard -->|"authenticates request"| node_clerk
node_auth_guard -->|"syncs user"| node_auth_service
node_auth_service -->|"upserts user"| node_database
node_search_api -->|"delegates"| node_search_service
node_video_service -->|"reads video"| node_database
node_workspace -.->|"uses requests"| node_api_client

click node_webapp "https://github.com/itz-snj/prism/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/itz-snj/prism/blob/main/frontend/src/pages/Dashboard.tsx"
click node_workspace "https://github.com/itz-snj/prism/blob/main/frontend/src/pages/Workspace.tsx"
click node_settings "https://github.com/itz-snj/prism/blob/main/frontend/src/pages/Settings.tsx"
click node_api_client "https://github.com/itz-snj/prism/blob/main/frontend/src/lib/api.ts"
click node_auth_guard "https://github.com/itz-snj/prism/blob/main/backend/src/auth/clerk-auth.guard.ts"
click node_auth_service "https://github.com/itz-snj/prism/blob/main/backend/src/auth/auth.service.ts"
click node_key_api "https://github.com/itz-snj/prism/blob/main/backend/src/api-keys/api-keys.controller.ts"
click node_key_service "https://github.com/itz-snj/prism/blob/main/backend/src/api-keys/api-keys.service.ts"
click node_ingest_api "https://github.com/itz-snj/prism/blob/main/backend/src/ingestion/ingestion.controller.ts"
click node_ingest_service "https://github.com/itz-snj/prism/blob/main/backend/src/ingestion/ingestion.service.ts"
click node_worker "https://github.com/itz-snj/prism/blob/main/backend/src/ingestion/ingestion.processor.ts"
click node_chat_api "https://github.com/itz-snj/prism/blob/main/backend/src/chat/chat.controller.ts"
click node_chat_service "https://github.com/itz-snj/prism/blob/main/backend/src/chat/chat.service.ts"
click node_search_api "https://github.com/itz-snj/prism/blob/main/backend/src/search/search.controller.ts"
click node_search_service "https://github.com/itz-snj/prism/blob/main/backend/src/search/search.service.ts"
click node_quiz_api "https://github.com/itz-snj/prism/blob/main/backend/src/quiz/quiz.controller.ts"
click node_quiz_service "https://github.com/itz-snj/prism/blob/main/backend/src/quiz/quiz.service.ts"
click node_video_service "https://github.com/itz-snj/prism/blob/main/backend/src/video/video.service.ts"
click node_database "https://github.com/itz-snj/prism/blob/main/backend/prisma/prisma.service.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_webapp,node_dashboard,node_workspace,node_settings,node_api_client toneBlue
class node_auth_guard,node_auth_service,node_key_api,node_key_service toneAmber
class node_ingest_api,node_ingest_service,node_worker toneMint
class node_chat_api,node_chat_service,node_search_api,node_search_service,node_quiz_api,node_quiz_service,node_video_service toneRose
class node_database,node_redis,node_gemini,node_youtube,node_clerk,node_learner toneIndigo
```

## Components

### Learning workspace

- [Web application](https://github.com/itz-snj/prism/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard](https://github.com/itz-snj/prism/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Video workspace](https://github.com/itz-snj/prism/blob/main/frontend/src/pages/Workspace.tsx): `frontend/src/pages/Workspace.tsx`
- [Settings](https://github.com/itz-snj/prism/blob/main/frontend/src/pages/Settings.tsx): `frontend/src/pages/Settings.tsx`
- [API client](https://github.com/itz-snj/prism/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Identity and keys

- [Clerk auth guard](https://github.com/itz-snj/prism/blob/main/backend/src/auth/clerk-auth.guard.ts): `backend/src/auth/clerk-auth.guard.ts`
- [User sync](https://github.com/itz-snj/prism/blob/main/backend/src/auth/auth.service.ts): `backend/src/auth/auth.service.ts`
- [API key routes](https://github.com/itz-snj/prism/blob/main/backend/src/api-keys/api-keys.controller.ts): `backend/src/api-keys/api-keys.controller.ts`
- [Encrypted API keys](https://github.com/itz-snj/prism/blob/main/backend/src/api-keys/api-keys.service.ts): `backend/src/api-keys/api-keys.service.ts`

### Video ingestion

- [Ingestion routes](https://github.com/itz-snj/prism/blob/main/backend/src/ingestion/ingestion.controller.ts): `backend/src/ingestion/ingestion.controller.ts`
- [Ingestion queue](https://github.com/itz-snj/prism/blob/main/backend/src/ingestion/ingestion.service.ts): `backend/src/ingestion/ingestion.service.ts`
- [Transcript worker](https://github.com/itz-snj/prism/blob/main/backend/src/ingestion/ingestion.processor.ts): `backend/src/ingestion/ingestion.processor.ts`

### Study features

- [Chat routes](https://github.com/itz-snj/prism/blob/main/backend/src/chat/chat.controller.ts): `backend/src/chat/chat.controller.ts`
- [RAG chat](https://github.com/itz-snj/prism/blob/main/backend/src/chat/chat.service.ts): `backend/src/chat/chat.service.ts`
- [Search routes](https://github.com/itz-snj/prism/blob/main/backend/src/search/search.controller.ts): `backend/src/search/search.controller.ts`
- [Vector search](https://github.com/itz-snj/prism/blob/main/backend/src/search/search.service.ts): `backend/src/search/search.service.ts`
- [Quiz routes](https://github.com/itz-snj/prism/blob/main/backend/src/quiz/quiz.controller.ts): `backend/src/quiz/quiz.controller.ts`
- [Quiz generation and results](https://github.com/itz-snj/prism/blob/main/backend/src/quiz/quiz.service.ts): `backend/src/quiz/quiz.service.ts`
- [Video access](https://github.com/itz-snj/prism/blob/main/backend/src/video/video.service.ts): `backend/src/video/video.service.ts`

### Persistence and services

- [PostgreSQL with pgvector](https://github.com/itz-snj/prism/blob/main/backend/prisma/prisma.service.ts): `backend/prisma/prisma.service.ts`
- **Redis and BullMQ**
- **Google Gemini**
- **YouTube captions**
- **Clerk identity**

### Other components

- **Learner**

## Connections

- Learner → Web application: uses
- Web application → Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Web application → Video workspace: routes to (evidence: `frontend/src/App.tsx`)
- Web application → Settings: routes to (evidence: `frontend/src/App.tsx`)
- Web application → API client: sets up auth (evidence: `frontend/src/App.tsx`)
- Learner → Ingestion routes: submits URL
- Ingestion routes → Ingestion queue: queues job (evidence: `backend/src/ingestion/ingestion.controller.ts`)
- Ingestion queue → Redis and BullMQ: adds job (evidence: `backend/src/ingestion/ingestion.service.ts`)
- Redis and BullMQ → Transcript worker: dispatches job
- Transcript worker → YouTube captions: fetches captions
- Transcript worker → Google Gemini: embeds chunks
- Transcript worker → PostgreSQL with pgvector: stores chunks (evidence: `backend/src/ingestion/ingestion.processor.ts`)
- Ingestion routes → Learner: streams progress (evidence: `backend/src/ingestion/ingestion.controller.ts`)
- Learner → Chat routes: asks question
- Chat routes → RAG chat: delegates (evidence: `backend/src/chat/chat.controller.ts`)
- RAG chat → Vector search: retrieves context (evidence: `backend/src/chat/chat.service.ts`)
- Vector search → Encrypted API keys: gets key (evidence: `backend/src/search/search.service.ts`)
- Vector search → Google Gemini: embeds query (evidence: `backend/src/search/search.service.ts`)
- Vector search → PostgreSQL with pgvector: searches vectors (evidence: `backend/src/search/search.service.ts`)
- RAG chat → Google Gemini: generates answer
- Learner → Quiz routes: requests quiz
- Quiz routes → Quiz generation and results: delegates (evidence: `backend/src/quiz/quiz.controller.ts`)
- Quiz generation and results → PostgreSQL with pgvector: reads and saves (evidence: `backend/src/quiz/quiz.service.ts`)
- Quiz generation and results → Encrypted API keys: gets key (evidence: `backend/src/quiz/quiz.service.ts`)
- Learner → API key routes: manages keys
- API key routes → Encrypted API keys: delegates (evidence: `backend/src/api-keys/api-keys.controller.ts`)
- Encrypted API keys → PostgreSQL with pgvector: stores encrypted keys (evidence: `backend/src/api-keys/api-keys.service.ts`)
- Clerk auth guard → Clerk identity: authenticates request (evidence: `backend/src/auth/clerk-auth.guard.ts`)
- Clerk auth guard → User sync: syncs user (evidence: `backend/src/auth/clerk-auth.guard.ts`)
- User sync → PostgreSQL with pgvector: upserts user (evidence: `backend/src/auth/auth.service.ts`)
- Search routes → Vector search: delegates (evidence: `backend/src/search/search.controller.ts`)
- Video access → PostgreSQL with pgvector: reads video (evidence: `backend/src/video/video.service.ts`)
- Video workspace → API client: uses requests
