# jaganparab02/samasocial-ai architecture

> Architecture diagram of the GitHub repository jaganparab02/samasocial-ai, 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/jaganparab02/samasocial-ai
- Repository: https://github.com/jaganparab02/samasocial-ai

## Overview

SamaSocial is an education platform with two user-facing workflows: a conversational assistant that ingests learning sources and answers with citations, and a course planner that generates and edits structured curricula. The graph follows documented frontend-to-backend access, then the sampled ingestion, retrieval, chat, and planner orchestration, with shared model and integration layers. Some router-to-service wiring and frontend learning-assistant wiring are not shown in the excerpts, so those connections are omitted or marked unverified rather than inferred.

Main entry points: [`backend/app/rag/document_pipeline.py`](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/rag/document_pipeline.py) (Document ingestion), [`backend/app/chat/chat_pipeline.py`](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/chat/chat_pipeline.py) (RAG chat orchestration), [`backend/app/planner/service.py`](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/planner/service.py) (Plan generation), [`backend/app/api`](https://github.com/jaganparab02/samasocial-ai/tree/main/backend/app/api) (FastAPI routers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend"]
  node_app["App routing<br/>[App.tsx]"]
  node_learning_page["Learning assistant"]
  node_planner_page["Course planner<br/>[CoursePlanner.tsx]"]
  node_chat_hook["Chat state<br/>[useChat.ts]"]
  node_planner_hook["Planner state<br/>[usePlanner.ts]"]
  node_api_client["API client<br/>[apiClient.ts]"]
  node_chat_service["Chat requests<br/>[chatService.ts]"]
  node_stream_service["Response streaming<br/>[streamService.ts]"]
  node_conversation_service["Conversation persistence"]
  node_plan_preview["Plan editor and preview"]
end

subgraph group_api["Backend API"]
  node_backend_api["FastAPI routers"]
end

subgraph group_learning["Learning Assistant"]
  node_ingestion["Document ingestion"]
  node_parsers["Source parsers"]
  node_chunking["Document chunking<br/>[chunk_service.py]"]
  node_source_registry["Source registry<br/>[source_service.py]"]
  node_chat_pipeline["RAG chat orchestration<br/>[chat_pipeline.py]"]
  node_retriever["Semantic retrieval<br/>[retriever.py]"]
end

subgraph group_planning["Course Planning"]
  node_planner_service["Plan generation<br/>[service.py]"]
  node_curriculum["Curriculum services"]
  node_recommendations["Recommendations"]
  node_export["Plan export<br/>[export_service.py]"]
end

subgraph group_foundation["Shared foundation"]
  node_embeddings["Embeddings<br/>[service.py]"]
  node_vector_store[("Vector store<br/>[service.py]")]
  node_prompt_builder["Prompt construction<br/>[prompt_builder.py]"]
  node_llm["Groq LLM client<br/>[client.py]"]
  node_session_manager["Session state<br/>[session_manager.py]"]
end

node_educator(("Educator"))
node_supabase[("Supabase")]

node_educator -->|"uses"| node_app
node_app -->|"routes to"| node_learning_page
node_app -->|"routes to"| node_planner_page
node_learning_page -->|"uses REST/SSE"| node_backend_api
node_planner_page -->|"uses"| node_planner_hook
node_planner_page -->|"renders"| node_plan_preview
node_chat_hook -->|"streams via"| node_stream_service
node_chat_hook -->|"calls"| node_chat_service
node_chat_hook -->|"persists with"| node_conversation_service
node_planner_hook -->|"persists with"| node_conversation_service
node_chat_service -->|"calls"| node_api_client
node_stream_service -->|"calls"| node_api_client
node_planner_hook -->|"uses REST"| node_backend_api
node_conversation_service -->|"reads/writes"| node_supabase
node_backend_api -.->|"dispatches to"| node_ingestion
node_backend_api -.->|"dispatches to"| node_chat_pipeline
node_backend_api -.->|"dispatches to"| node_planner_service
node_ingestion -->|"extracts with"| node_parsers
node_ingestion -->|"chunks via"| node_chunking
node_ingestion -->|"generates"| node_embeddings
node_ingestion -->|"indexes in"| node_vector_store
node_ingestion -->|"registers source"| node_source_registry
node_retriever -->|"embeds query"| node_embeddings
node_retriever -->|"searches"| node_vector_store
node_chat_pipeline -->|"manages sessions"| node_session_manager
node_chat_pipeline -->|"retrieves context"| node_retriever
node_chat_pipeline -->|"builds prompts"| node_prompt_builder
node_chat_pipeline -->|"generates answer"| node_llm
node_planner_service -->|"retrieves context"| node_retriever
node_planner_service -->|"generates plans"| node_llm
node_planner_service -->|"uses"| node_curriculum
node_planner_service -->|"uses"| node_recommendations
node_plan_preview -->|"edits plan"| node_planner_hook
node_plan_preview -.->|"exports plan"| node_export

click node_app "https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/App.tsx"
click node_learning_page "https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/pages/LearningAssistant.tsx"
click node_planner_page "https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/pages/CoursePlanner.tsx"
click node_chat_hook "https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/hooks/useChat.ts"
click node_planner_hook "https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/hooks/usePlanner.ts"
click node_api_client "https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/services/apiClient.ts"
click node_chat_service "https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/services/chatService.ts"
click node_stream_service "https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/services/streamService.ts"
click node_conversation_service "https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/services/conversationService.ts"
click node_backend_api "https://github.com/jaganparab02/samasocial-ai/tree/main/backend/app/api"
click node_ingestion "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/rag/document_pipeline.py"
click node_parsers "https://github.com/jaganparab02/samasocial-ai/tree/main/backend/app/parsers"
click node_chunking "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/rag/chunk_service.py"
click node_embeddings "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/embeddings/service.py"
click node_vector_store "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/vectordb/service.py"
click node_source_registry "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/services/source_service.py"
click node_chat_pipeline "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/chat/chat_pipeline.py"
click node_retriever "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/rag/retriever.py"
click node_prompt_builder "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/llm/prompt_builder.py"
click node_llm "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/llm/client.py"
click node_session_manager "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/chat/session_manager.py"
click node_planner_service "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/planner/service.py"
click node_curriculum "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/services/curriculum_service.py"
click node_recommendations "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/services/recommendation_service.py"
click node_export "https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/services/export_service.py"
click node_plan_preview "https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/components/planner/CoursePlanPreview.tsx"

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,node_learning_page,node_planner_page,node_chat_hook,node_planner_hook,node_api_client,node_chat_service,node_stream_service,node_conversation_service,node_plan_preview toneBlue
class node_backend_api,node_supabase toneAmber
class node_ingestion,node_parsers,node_chunking,node_source_registry,node_chat_pipeline,node_retriever toneMint
class node_planner_service,node_curriculum,node_recommendations,node_export toneRose
class node_embeddings,node_vector_store,node_prompt_builder,node_llm,node_session_manager,node_educator toneIndigo
```

## Components

### Frontend

- [App routing](https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Learning assistant](https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/pages/LearningAssistant.tsx): `frontend/src/pages/LearningAssistant.tsx`
- [Course planner](https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/pages/CoursePlanner.tsx): `frontend/src/pages/CoursePlanner.tsx`
- [Chat state](https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/hooks/useChat.ts): `frontend/src/hooks/useChat.ts`
- [Planner state](https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/hooks/usePlanner.ts): `frontend/src/hooks/usePlanner.ts`
- [API client](https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`
- [Chat requests](https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/services/chatService.ts): `frontend/src/services/chatService.ts`
- [Response streaming](https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/services/streamService.ts): `frontend/src/services/streamService.ts`
- [Conversation persistence](https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/services/conversationService.ts): `frontend/src/services/conversationService.ts`
- [Plan editor and preview](https://github.com/jaganparab02/samasocial-ai/blob/main/frontend/src/components/planner/CoursePlanPreview.tsx): `frontend/src/components/planner/CoursePlanPreview.tsx`

### Backend API

- [FastAPI routers](https://github.com/jaganparab02/samasocial-ai/tree/main/backend/app/api): `backend/app/api`

### Learning Assistant

- [Document ingestion](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/rag/document_pipeline.py): `backend/app/rag/document_pipeline.py`
- [Source parsers](https://github.com/jaganparab02/samasocial-ai/tree/main/backend/app/parsers): `backend/app/parsers`
- [Document chunking](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/rag/chunk_service.py): `backend/app/rag/chunk_service.py`
- [Source registry](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/services/source_service.py): `backend/app/services/source_service.py`
- [RAG chat orchestration](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/chat/chat_pipeline.py): `backend/app/chat/chat_pipeline.py`
- [Semantic retrieval](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`

### Course Planning

- [Plan generation](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/planner/service.py): `backend/app/planner/service.py`
- [Curriculum services](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/services/curriculum_service.py): `backend/app/services/curriculum_service.py`
- [Recommendations](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/services/recommendation_service.py): `backend/app/services/recommendation_service.py`
- [Plan export](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/services/export_service.py): `backend/app/services/export_service.py`

### Shared foundation

- [Embeddings](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/embeddings/service.py): `backend/app/embeddings/service.py`
- [Vector store](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/vectordb/service.py): `backend/app/vectordb/service.py`
- [Prompt construction](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/llm/prompt_builder.py): `backend/app/llm/prompt_builder.py`
- [Groq LLM client](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/llm/client.py): `backend/app/llm/client.py`
- [Session state](https://github.com/jaganparab02/samasocial-ai/blob/main/backend/app/chat/session_manager.py): `backend/app/chat/session_manager.py`

### Other components

- **Educator**
- **Supabase**

## Connections

- Educator → App routing: uses (evidence: `README.md`)
- App routing → Learning assistant: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Course planner: routes to (evidence: `frontend/src/App.tsx`)
- Learning assistant → FastAPI routers: uses REST/SSE (evidence: `README.md`)
- Course planner → Planner state: uses (evidence: `frontend/src/pages/CoursePlanner.tsx`)
- Course planner → Plan editor and preview: renders (evidence: `frontend/src/pages/CoursePlanner.tsx`)
- Chat state → Response streaming: streams via (evidence: `frontend/src/hooks/useChat.ts`)
- Chat state → Chat requests: calls (evidence: `frontend/src/hooks/useChat.ts`)
- Chat state → Conversation persistence: persists with (evidence: `frontend/src/hooks/useChat.ts`)
- Planner state → Conversation persistence: persists with (evidence: `frontend/src/hooks/usePlanner.ts`)
- Chat requests → API client: calls (evidence: `frontend/src/services/chatService.ts`)
- Response streaming → API client: calls (evidence: `frontend/src/services/streamService.ts`)
- Planner state → FastAPI routers: uses REST (evidence: `README.md`)
- Conversation persistence → Supabase: reads/writes (evidence: `frontend/src/services/conversationService.ts`)
- FastAPI routers → Document ingestion: dispatches to
- FastAPI routers → RAG chat orchestration: dispatches to
- FastAPI routers → Plan generation: dispatches to
- Document ingestion → Source parsers: extracts with (evidence: `backend/app/rag/document_pipeline.py`)
- Document ingestion → Document chunking: chunks via (evidence: `backend/app/rag/document_pipeline.py`)
- Document ingestion → Embeddings: generates (evidence: `backend/app/rag/document_pipeline.py`)
- Document ingestion → Vector store: indexes in (evidence: `backend/app/rag/document_pipeline.py`)
- Document ingestion → Source registry: registers source (evidence: `backend/app/rag/document_pipeline.py`)
- Semantic retrieval → Embeddings: embeds query (evidence: `backend/app/rag/retriever.py`)
- Semantic retrieval → Vector store: searches (evidence: `backend/app/rag/retriever.py`)
- RAG chat orchestration → Session state: manages sessions (evidence: `backend/app/chat/chat_pipeline.py`)
- RAG chat orchestration → Semantic retrieval: retrieves context (evidence: `backend/app/chat/chat_pipeline.py`)
- RAG chat orchestration → Prompt construction: builds prompts (evidence: `backend/app/chat/chat_pipeline.py`)
- RAG chat orchestration → Groq LLM client: generates answer (evidence: `backend/app/chat/chat_pipeline.py`)
- Plan generation → Semantic retrieval: retrieves context (evidence: `backend/app/planner/service.py`)
- Plan generation → Groq LLM client: generates plans (evidence: `backend/app/planner/service.py`)
- Plan generation → Curriculum services: uses (evidence: `backend/app/planner/service.py`)
- Plan generation → Recommendations: uses (evidence: `backend/app/planner/service.py`)
- Plan editor and preview → Planner state: edits plan (evidence: `frontend/src/components/planner/CoursePlanPreview.tsx`)
- Plan editor and preview → Plan export: exports plan
