# uday-sr/second-brain architecture

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

- Interactive diagram: https://gitdiagram.com/uday-sr/second-brain
- Repository: https://github.com/uday-sr/second-brain

## Overview

Second Brain is a user-facing knowledge library: users sign in, save content, and explore saved items; supported sources can then be indexed for contextual Q&A. The React app talks to the Node API for accounts and content, while the Python AI service exposes separate ingestion and question-answering endpoints. Its ingestion path loads a source, chunks and embeds it, then stores an index; Q&A retrieves context and asks Ollama for an answer. The README describes semantic search and summaries, though the sampled AI endpoint shows Q&A rather than a separate summary flow. Some frontend-to-AI and backend-to-AI wiring is not shown, so those connections are omitted.

Main entry points: [`ai_service/app/main.py`](https://github.com/uday-sr/second-brain/blob/main/ai_service/app/main.py) (AI service API), [`frontend/src/lib/api.ts`](https://github.com/uday-sr/second-brain/blob/main/frontend/src/lib/api.ts) (API clients), [`frontend/src/routes/Home.tsx`](https://github.com/uday-sr/second-brain/blob/main/frontend/src/routes/Home.tsx) (Content home), [`frontend/src/components/Card.tsx`](https://github.com/uday-sr/second-brain/blob/main/frontend/src/components/Card.tsx) (Content cards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_webapp["React app<br/>[main.tsx]"]
  node_intro["Intro and auth<br/>[Intro.tsx]"]
  node_authmodal["Sign-in modal<br/>[AuthModal.tsx]"]
  node_home["Content home<br/>[Home.tsx]"]
  node_contentmodal["Add content<br/>[ContentModal.tsx]"]
  node_cards["Content cards<br/>[Card.tsx]"]
  node_askui["Ask AI UI<br/>[AskAi.tsx]"]
  node_api["API clients<br/>[api.ts]"]
end

subgraph group_backend["Content API"]
  node_nodeapi["Express app<br/>[app.ts]"]
  node_users["User routes<br/>[user.ts]"]
  node_content["Content routes<br/>[content.ts]"]
  node_authmw["User middleware<br/>[user.ts]"]
end

subgraph group_ingestion["AI ingestion"]
  node_ai["AI service API<br/>[main.py]"]
  node_loaders["Source loader registry<br/>[__init__.py]"]
  node_youtube["YouTube loader<br/>[youtube.py]"]
  node_yttools["Transcript extraction<br/>[downloader.py]"]
  node_chunker["Text chunker<br/>[chunker.py]"]
  node_embedder["Embedding model<br/>[embedder.py]"]
end

subgraph group_qa["AI retrieval and Q&amp;A"]
  node_retriever["Vector retrieval<br/>[retriever.py]"]
  node_llm["Answer generation<br/>[llm.py]"]
end

subgraph group_state["Persistence and identity"]
  node_prisma["Prisma client<br/>[prisma.ts]"]
  node_pg[("PostgreSQL")]
  node_indexstore[("Index and status store<br/>[store.py]")]
end

node_user(("User"))
node_ollama{{"Ollama"}}

node_user -->|"uses"| node_webapp
node_webapp -->|"renders"| node_intro
node_intro -->|"opens"| node_authmodal
node_authmodal -->|"submits credentials"| node_api
node_home -->|"fetches content"| node_api
node_home -->|"opens"| node_contentmodal
node_home -->|"renders"| node_cards
node_cards -->|"renders"| node_askui
node_cards -->|"calls"| node_api
node_contentmodal -->|"creates content"| node_api
node_api -->|"requests"| node_nodeapi
node_nodeapi -->|"registers route"| node_users
node_nodeapi -->|"registers route"| node_content
node_users -->|"queries"| node_prisma
node_content -->|"queries"| node_prisma
node_users -->|"uses"| node_authmw
node_content -->|"uses"| node_authmw
node_prisma -.->|"persists data"| node_pg
node_ai -->|"loads source"| node_loaders
node_loaders -->|"dispatches"| node_youtube
node_youtube -->|"extracts transcript"| node_yttools
node_ai -->|"chunks segments"| node_chunker
node_ai -->|"embeds chunks"| node_embedder
node_ai -->|"saves index"| node_indexstore
node_ai -->|"reads status and index"| node_indexstore
node_ai -->|"retrieves matches"| node_retriever
node_ai -->|"requests answer"| node_llm
node_llm -->|"generates response"| node_ollama

click node_webapp "https://github.com/uday-sr/second-brain/blob/main/frontend/src/main.tsx"
click node_intro "https://github.com/uday-sr/second-brain/blob/main/frontend/src/routes/Intro.tsx"
click node_authmodal "https://github.com/uday-sr/second-brain/blob/main/frontend/src/components/AuthModal.tsx"
click node_home "https://github.com/uday-sr/second-brain/blob/main/frontend/src/routes/Home.tsx"
click node_contentmodal "https://github.com/uday-sr/second-brain/blob/main/frontend/src/components/ContentModal.tsx"
click node_cards "https://github.com/uday-sr/second-brain/blob/main/frontend/src/components/Card.tsx"
click node_askui "https://github.com/uday-sr/second-brain/blob/main/frontend/src/components/AskAi.tsx"
click node_api "https://github.com/uday-sr/second-brain/blob/main/frontend/src/lib/api.ts"
click node_nodeapi "https://github.com/uday-sr/second-brain/blob/main/backend/src/server/app.ts"
click node_users "https://github.com/uday-sr/second-brain/blob/main/backend/src/Routers/user.ts"
click node_content "https://github.com/uday-sr/second-brain/blob/main/backend/src/Routers/content.ts"
click node_authmw "https://github.com/uday-sr/second-brain/blob/main/backend/src/middlewares/user.ts"
click node_prisma "https://github.com/uday-sr/second-brain/blob/main/backend/src/lib/prisma.ts"
click node_ai "https://github.com/uday-sr/second-brain/blob/main/ai_service/app/main.py"
click node_loaders "https://github.com/uday-sr/second-brain/blob/main/ai_service/app/loaders/__init__.py"
click node_youtube "https://github.com/uday-sr/second-brain/blob/main/ai_service/app/loaders/youtube.py"
click node_yttools "https://github.com/uday-sr/second-brain/blob/main/ai_service/app/yt/downloader.py"
click node_chunker "https://github.com/uday-sr/second-brain/blob/main/ai_service/app/rag/chunker.py"
click node_embedder "https://github.com/uday-sr/second-brain/blob/main/ai_service/app/rag/embedder.py"
click node_indexstore "https://github.com/uday-sr/second-brain/blob/main/ai_service/app/store.py"
click node_retriever "https://github.com/uday-sr/second-brain/blob/main/ai_service/app/rag/retriever.py"
click node_llm "https://github.com/uday-sr/second-brain/blob/main/ai_service/app/rag/llm.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_webapp,node_intro,node_authmodal,node_home,node_contentmodal,node_cards,node_askui,node_api,node_user toneBlue
class node_nodeapi,node_users,node_content,node_authmw toneAmber
class node_ai,node_loaders,node_youtube,node_yttools,node_chunker,node_embedder toneMint
class node_retriever,node_llm toneRose
class node_prisma,node_pg,node_indexstore,node_ollama toneIndigo
```

## Components

### Web application

- [React app](https://github.com/uday-sr/second-brain/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Intro and auth](https://github.com/uday-sr/second-brain/blob/main/frontend/src/routes/Intro.tsx): `frontend/src/routes/Intro.tsx`
- [Sign-in modal](https://github.com/uday-sr/second-brain/blob/main/frontend/src/components/AuthModal.tsx): `frontend/src/components/AuthModal.tsx`
- [Content home](https://github.com/uday-sr/second-brain/blob/main/frontend/src/routes/Home.tsx): `frontend/src/routes/Home.tsx`
- [Add content](https://github.com/uday-sr/second-brain/blob/main/frontend/src/components/ContentModal.tsx): `frontend/src/components/ContentModal.tsx`
- [Content cards](https://github.com/uday-sr/second-brain/blob/main/frontend/src/components/Card.tsx): `frontend/src/components/Card.tsx`
- [Ask AI UI](https://github.com/uday-sr/second-brain/blob/main/frontend/src/components/AskAi.tsx): `frontend/src/components/AskAi.tsx`
- [API clients](https://github.com/uday-sr/second-brain/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Content API

- [Express app](https://github.com/uday-sr/second-brain/blob/main/backend/src/server/app.ts): `backend/src/server/app.ts`
- [User routes](https://github.com/uday-sr/second-brain/blob/main/backend/src/Routers/user.ts): `backend/src/Routers/user.ts`
- [Content routes](https://github.com/uday-sr/second-brain/blob/main/backend/src/Routers/content.ts): `backend/src/Routers/content.ts`
- [User middleware](https://github.com/uday-sr/second-brain/blob/main/backend/src/middlewares/user.ts): `backend/src/middlewares/user.ts`

### AI ingestion

- [AI service API](https://github.com/uday-sr/second-brain/blob/main/ai_service/app/main.py): `ai_service/app/main.py`
- [Source loader registry](https://github.com/uday-sr/second-brain/blob/main/ai_service/app/loaders/__init__.py): `ai_service/app/loaders/__init__.py`
- [YouTube loader](https://github.com/uday-sr/second-brain/blob/main/ai_service/app/loaders/youtube.py): `ai_service/app/loaders/youtube.py`
- [Transcript extraction](https://github.com/uday-sr/second-brain/blob/main/ai_service/app/yt/downloader.py): `ai_service/app/yt/downloader.py`
- [Text chunker](https://github.com/uday-sr/second-brain/blob/main/ai_service/app/rag/chunker.py): `ai_service/app/rag/chunker.py`
- [Embedding model](https://github.com/uday-sr/second-brain/blob/main/ai_service/app/rag/embedder.py): `ai_service/app/rag/embedder.py`

### AI retrieval and Q&A

- [Vector retrieval](https://github.com/uday-sr/second-brain/blob/main/ai_service/app/rag/retriever.py): `ai_service/app/rag/retriever.py`
- [Answer generation](https://github.com/uday-sr/second-brain/blob/main/ai_service/app/rag/llm.py): `ai_service/app/rag/llm.py`

### Persistence and identity

- [Prisma client](https://github.com/uday-sr/second-brain/blob/main/backend/src/lib/prisma.ts): `backend/src/lib/prisma.ts`
- **PostgreSQL**
- [Index and status store](https://github.com/uday-sr/second-brain/blob/main/ai_service/app/store.py): `ai_service/app/store.py`

### Other components

- **User**
- **Ollama**

## Connections

- User → React app: uses
- React app → Intro and auth: renders
- Intro and auth → Sign-in modal: opens (evidence: `frontend/src/routes/Intro.tsx`)
- Sign-in modal → API clients: submits credentials (evidence: `frontend/src/components/AuthModal.tsx`)
- Content home → API clients: fetches content (evidence: `frontend/src/routes/Home.tsx`)
- Content home → Add content: opens (evidence: `frontend/src/routes/Home.tsx`)
- Content home → Content cards: renders (evidence: `frontend/src/routes/Home.tsx`)
- Content cards → Ask AI UI: renders (evidence: `frontend/src/components/Card.tsx`)
- Content cards → API clients: calls (evidence: `frontend/src/components/Card.tsx`)
- Add content → API clients: creates content (evidence: `frontend/src/components/ContentModal.tsx`)
- API clients → Express app: requests (evidence: `frontend/src/lib/api.ts`)
- Express app → User routes: registers route (evidence: `backend/src/server/app.ts`)
- Express app → Content routes: registers route (evidence: `backend/src/server/app.ts`)
- User routes → Prisma client: queries (evidence: `backend/src/Routers/user.ts`)
- Content routes → Prisma client: queries (evidence: `backend/src/Routers/content.ts`)
- User routes → User middleware: uses (evidence: `backend/src/Routers/user.ts`)
- Content routes → User middleware: uses (evidence: `backend/src/Routers/content.ts`)
- Prisma client → PostgreSQL: persists data
- AI service API → Source loader registry: loads source (evidence: `ai_service/app/main.py`)
- Source loader registry → YouTube loader: dispatches (evidence: `ai_service/app/loaders/__init__.py`)
- YouTube loader → Transcript extraction: extracts transcript (evidence: `ai_service/app/loaders/youtube.py`)
- AI service API → Text chunker: chunks segments (evidence: `ai_service/app/main.py`)
- AI service API → Embedding model: embeds chunks (evidence: `ai_service/app/main.py`)
- AI service API → Index and status store: saves index (evidence: `ai_service/app/main.py`)
- AI service API → Index and status store: reads status and index (evidence: `ai_service/app/main.py`)
- AI service API → Vector retrieval: retrieves matches (evidence: `ai_service/app/main.py`)
- AI service API → Answer generation: requests answer (evidence: `ai_service/app/main.py`)
- Answer generation → Ollama: generates response (evidence: `ai_service/app/rag/llm.py`)
