# sridhar281/vivaforge architecture

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

- Interactive diagram: https://gitdiagram.com/sridhar281/vivaforge
- Repository: https://github.com/sridhar281/vivaforge

## Overview

VivaForge turns uploaded lectures and documents into grounded study materials and adaptive practice. The main path is upload, media/document extraction, chunking and indexing, then summary/concept generation; learners use those outputs for viva sessions, flashcards, explain-back, knowledge-gap views and revision planning. The frontend reaches FastAPI routes, while PostgreSQL stores relational records and Chroma supports scoped retrieval. Feature-service internals beyond the sampled excerpts are represented from the README and SOURCE INDEX; those sources establish documented capabilities and imports, not every runtime call.

Main entry points: [`backend/app/services/processing_service.py`](https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/processing_service.py) (Processing pipeline), [`backend/app/rag/retriever.py`](https://github.com/sridhar281/vivaforge/blob/main/backend/app/rag/retriever.py) (RAG retriever), [`backend/app/services/summary_service.py`](https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/summary_service.py) (Summary and concepts), [`backend/app/main.py`](https://github.com/sridhar281/vivaforge/blob/main/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner experience"]
  node_web["Next.js app"]
  node_web_services["API services"]
  node_api_client["HTTP client<br/>[api-client.ts]"]
end

subgraph group_api["API and identity"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth_api["Auth routes<br/>[auth.py]"]
  node_content_api["Content routes<br/>[content.py]"]
  node_feature_apis["Learning routes"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_content_service["Content service<br/>[content_service.py]"]
end

subgraph group_ingest["Content ingestion"]
  node_processing["Processing pipeline"]
  node_media["Media extraction"]
  node_chunking["Chunking<br/>[chunker.py]"]
end

subgraph group_learning["Learning features"]
  node_summary["Summary and concepts<br/>[summary_service.py]"]
  node_viva["Adaptive viva"]
  node_learning_services["Study features"]
  node_pdf["Viva PDF"]
end

subgraph group_platform["AI and persistence"]
  node_retriever["RAG retriever<br/>[retriever.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_vector_store["Vector store<br/>[vector_store.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_postgres[("PostgreSQL")]
  node_chroma[("Chroma")]
  node_artifacts[("Artifact files")]
end

node_learner(("Learner"))
node_groq["Groq API"]

node_learner -->|"uses"| node_web
node_web -->|"requests"| node_web_services
node_web_services -.->|"uses"| node_api_client
node_api_client -->|"calls API"| node_app
node_app -->|"routes to"| node_auth_api
node_app -->|"routes to"| node_content_api
node_app -->|"routes to"| node_feature_apis
node_auth_api -->|"delegates to"| node_auth_service
node_content_api -->|"delegates to"| node_content_service
node_content_api -->|"starts processing"| node_processing
node_processing -->|"extracts text"| node_media
node_processing -->|"chunks source"| node_chunking
node_processing -->|"generates materials"| node_summary
node_processing -->|"embeds chunks"| node_embeddings
node_processing -->|"stores chunks"| node_vector_store
node_summary -->|"reads chunks"| node_retriever
node_summary -->|"generates outputs"| node_llm
node_summary -.->|"saves concepts"| node_postgres
node_summary -->|"writes summary"| node_artifacts
node_retriever -->|"embeds query"| node_embeddings
node_retriever -->|"queries vectors"| node_vector_store
node_retriever -->|"loads chunks"| node_postgres
node_vector_store -->|"queries and stores"| node_chroma
node_llm -->|"calls"| node_groq
node_feature_apis -->|"starts adaptive viva"| node_viva
node_viva -->|"retrieves context"| node_retriever
node_viva -->|"generates and evaluates"| node_llm
node_viva -.->|"updates session mastery"| node_postgres
node_feature_apis -->|"serves study features"| node_learning_services
node_feature_apis -->|"generates PDF"| node_pdf
node_learning_services -->|"uses retrieval"| node_retriever
node_content_service -.->|"reads content"| node_postgres

click node_web "https://github.com/sridhar281/vivaforge/tree/main/frontend/app"
click node_web_services "https://github.com/sridhar281/vivaforge/tree/main/frontend/services"
click node_api_client "https://github.com/sridhar281/vivaforge/blob/main/frontend/lib/api-client.ts"
click node_app "https://github.com/sridhar281/vivaforge/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/sridhar281/vivaforge/blob/main/backend/app/api/auth.py"
click node_content_api "https://github.com/sridhar281/vivaforge/blob/main/backend/app/api/content.py"
click node_feature_apis "https://github.com/sridhar281/vivaforge/tree/main/backend/app/api"
click node_auth_service "https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/auth_service.py"
click node_content_service "https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/content_service.py"
click node_processing "https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/processing_service.py"
click node_media "https://github.com/sridhar281/vivaforge/tree/main/backend/app/media"
click node_chunking "https://github.com/sridhar281/vivaforge/blob/main/backend/app/rag/chunker.py"
click node_summary "https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/summary_service.py"
click node_viva "https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/viva_session_service.py"
click node_learning_services "https://github.com/sridhar281/vivaforge/tree/main/backend/app/services"
click node_pdf "https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/viva_pdf_service.py"
click node_retriever "https://github.com/sridhar281/vivaforge/blob/main/backend/app/rag/retriever.py"
click node_embeddings "https://github.com/sridhar281/vivaforge/blob/main/backend/app/rag/embeddings.py"
click node_vector_store "https://github.com/sridhar281/vivaforge/blob/main/backend/app/rag/vector_store.py"
click node_llm "https://github.com/sridhar281/vivaforge/blob/main/backend/app/ai/llm_client.py"

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_web,node_web_services,node_api_client toneBlue
class node_app,node_auth_api,node_content_api,node_feature_apis,node_auth_service,node_content_service toneAmber
class node_processing,node_media,node_chunking,node_groq toneMint
class node_summary,node_viva,node_learning_services,node_pdf toneRose
class node_retriever,node_embeddings,node_vector_store,node_llm,node_postgres,node_chroma,node_artifacts,node_learner toneIndigo
```

## Components

### Learner experience

- [Next.js app](https://github.com/sridhar281/vivaforge/tree/main/frontend/app): `frontend/app`
- [API services](https://github.com/sridhar281/vivaforge/tree/main/frontend/services): `frontend/services`
- [HTTP client](https://github.com/sridhar281/vivaforge/blob/main/frontend/lib/api-client.ts): `frontend/lib/api-client.ts`

### API and identity

- [FastAPI app](https://github.com/sridhar281/vivaforge/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/sridhar281/vivaforge/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Content routes](https://github.com/sridhar281/vivaforge/blob/main/backend/app/api/content.py): `backend/app/api/content.py`
- [Learning routes](https://github.com/sridhar281/vivaforge/tree/main/backend/app/api): `backend/app/api`
- [Auth service](https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Content service](https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/content_service.py): `backend/app/services/content_service.py`

### Content ingestion

- [Processing pipeline](https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/processing_service.py): `backend/app/services/processing_service.py`
- [Media extraction](https://github.com/sridhar281/vivaforge/tree/main/backend/app/media): `backend/app/media`
- [Chunking](https://github.com/sridhar281/vivaforge/blob/main/backend/app/rag/chunker.py): `backend/app/rag/chunker.py`

### Learning features

- [Summary and concepts](https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/summary_service.py): `backend/app/services/summary_service.py`
- [Adaptive viva](https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/viva_session_service.py): `backend/app/services/viva_session_service.py`
- [Study features](https://github.com/sridhar281/vivaforge/tree/main/backend/app/services): `backend/app/services`
- [Viva PDF](https://github.com/sridhar281/vivaforge/blob/main/backend/app/services/viva_pdf_service.py): `backend/app/services/viva_pdf_service.py`

### AI and persistence

- [RAG retriever](https://github.com/sridhar281/vivaforge/blob/main/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`
- [Embeddings](https://github.com/sridhar281/vivaforge/blob/main/backend/app/rag/embeddings.py): `backend/app/rag/embeddings.py`
- [Vector store](https://github.com/sridhar281/vivaforge/blob/main/backend/app/rag/vector_store.py): `backend/app/rag/vector_store.py`
- [LLM client](https://github.com/sridhar281/vivaforge/blob/main/backend/app/ai/llm_client.py): `backend/app/ai/llm_client.py`
- **PostgreSQL**
- **Chroma**
- **Artifact files**

### Other components

- **Learner**
- **Groq API**

## Connections

- Learner → Next.js app: uses (evidence: `README.md`)
- Next.js app → API services: requests (evidence: `README.md`)
- API services → HTTP client: uses
- HTTP client → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Auth routes: routes to (evidence: `backend/app/main.py`)
- FastAPI app → Content routes: routes to (evidence: `backend/app/main.py`)
- FastAPI app → Learning routes: routes to (evidence: `backend/app/main.py`)
- Auth routes → Auth service: delegates to (evidence: `backend/app/api/auth.py`)
- Content routes → Content service: delegates to (evidence: `backend/app/api/content.py`)
- Content routes → Processing pipeline: starts processing (evidence: `backend/app/api/content.py`)
- Processing pipeline → Media extraction: extracts text (evidence: `backend/app/services/processing_service.py`)
- Processing pipeline → Chunking: chunks source (evidence: `backend/app/services/processing_service.py`)
- Processing pipeline → Summary and concepts: generates materials (evidence: `backend/app/services/processing_service.py`)
- Processing pipeline → Embeddings: embeds chunks (evidence: `backend/app/services/processing_service.py`)
- Processing pipeline → Vector store: stores chunks (evidence: `backend/app/services/processing_service.py`)
- Summary and concepts → RAG retriever: reads chunks (evidence: `backend/app/services/summary_service.py`)
- Summary and concepts → LLM client: generates outputs (evidence: `backend/app/services/summary_service.py`)
- Summary and concepts → PostgreSQL: saves concepts
- Summary and concepts → Artifact files: writes summary (evidence: `backend/app/services/summary_service.py`)
- RAG retriever → Embeddings: embeds query (evidence: `backend/app/rag/retriever.py`)
- RAG retriever → Vector store: queries vectors (evidence: `backend/app/rag/retriever.py`)
- RAG retriever → PostgreSQL: loads chunks (evidence: `backend/app/rag/retriever.py`)
- Vector store → Chroma: queries and stores (evidence: `README.md`)
- LLM client → Groq API: calls (evidence: `backend/app/ai/llm_client.py`)
- Learning routes → Adaptive viva: starts adaptive viva (evidence: `backend/app/api/viva.py`)
- Adaptive viva → RAG retriever: retrieves context (evidence: `backend/app/services/viva_session_service.py`)
- Adaptive viva → LLM client: generates and evaluates (evidence: `backend/app/services/viva_session_service.py`)
- Adaptive viva → PostgreSQL: updates session mastery
- Learning routes → Study features: serves study features (evidence: `README.md`)
- Learning routes → Viva PDF: generates PDF (evidence: `backend/app/api/viva.py`)
- Study features → RAG retriever: uses retrieval (evidence: `backend/app/rag/retriever.py`)
- Content service → PostgreSQL: reads content
