# anujsomani/second-brain architecture

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

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

## Overview

SecondBrain is a web knowledge hub: users authenticate, save and organize links or documents, and later ask questions grounded in their saved material. The backend ingestion path extracts metadata and text, chunks and embeds it, then persists searchable content; chat retrieves matching chunks and asks Gemini to answer. The UI also supports shared read-only brains, profile management, and account recovery. Edges below are limited to relationships shown in excerpts, the source index, or README; several documented capabilities lack sampled implementation excerpts, so their internal links are not expanded.

Main entry points: [`backend/src/ai/ingest.ts`](https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/ingest.ts) (Content ingestion), [`backend/src/prisma.ts`](https://github.com/anujsomani/second-brain/blob/main/backend/src/prisma.ts) (PostgreSQL database), [`frontend/src/App.tsx`](https://github.com/anujsomani/second-brain/blob/main/frontend/src/App.tsx) (Route application), [`backend/src/auth.ts`](https://github.com/anujsomani/second-brain/blob/main/backend/src/auth.ts) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Route application<br/>[App.tsx]"]
  node_brainpage["Knowledge workspace<br/>[BrainPage.tsx]"]
  node_chatpage["AI chat page<br/>[ChatPage.tsx]"]
  node_sharedpage["Shared brain page"]
  node_profilepage["Profile page<br/>[ProfilePage.tsx]"]
  node_authclient["Account API client<br/>[auth-api.ts]"]
  node_contentclient["Content API client<br/>[content-api.ts]"]
end

subgraph group_accounts["Accounts and sharing"]
  node_authroutes["Authentication routes<br/>[auth.ts]"]
  node_oauth["Google OAuth<br/>[oauth.ts]"]
  node_userguard["User middleware<br/>[user.ts]"]
  node_email["Verification email<br/>[sendEmail.ts]"]
end

subgraph group_knowledge["Content management"]
  node_contentroutes["Content routes<br/>[content.ts]"]
  node_ingest["Content ingestion<br/>[ingest.ts]"]
  node_strategy["Extraction strategy"]
  node_extractors["Format extractors"]
  node_metadata["Metadata extraction"]
  node_urlguard["URL safety<br/>[urlsafety.ts]"]
  node_chunker["Text chunking<br/>[chunk.ts]"]
end

subgraph group_ai["AI knowledge services"]
  node_embedding["Gemini embeddings<br/>[embedding.ts]"]
  node_retrieval["Vector retrieval<br/>[retrieval.ts]"]
  node_chat["Chat orchestration<br/>[chat.ts]"]
  node_llm["Answer generation<br/>[llm.ts]"]
end

subgraph group_persistence["Persistence"]
  node_db[("PostgreSQL database<br/>[prisma.ts]")]
end

node_user(("User"))
node_gemini["Google Gemini"]
node_resend["Resend email"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_brainpage
node_app -->|"routes to"| node_chatpage
node_app -->|"routes to"| node_sharedpage
node_app -->|"routes to"| node_profilepage
node_brainpage -->|"fetches content"| node_contentclient
node_contentclient -.->|"HTTP requests"| node_contentroutes
node_authclient -.->|"HTTP requests"| node_authroutes
node_authroutes -->|"reads and writes"| node_db
node_authroutes -->|"sends OTP"| node_email
node_email -.->|"sends email"| node_resend
node_authroutes -->|"guards logout"| node_userguard
node_oauth -->|"reads and writes"| node_db
node_contentroutes -.->|"manages content"| node_db
node_contentroutes -.->|"starts ingestion"| node_ingest
node_ingest -->|"reads and writes"| node_db
node_ingest -->|"selects strategy"| node_strategy
node_ingest -->|"extracts content"| node_extractors
node_ingest -->|"extracts metadata"| node_metadata
node_metadata -->|"checks URLs"| node_urlguard
node_ingest -->|"chunks text"| node_chunker
node_ingest -->|"embeds chunks"| node_embedding
node_embedding -->|"requests embeddings"| node_gemini
node_ingest -->|"stores vectors"| node_db
node_chatpage -.->|"submits questions"| node_chat
node_chat -->|"retrieves context"| node_retrieval
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"searches vectors"| node_db
node_chat -.->|"generates answer"| node_llm
node_llm -->|"generates response"| node_gemini
node_sharedpage -.->|"loads shared brain"| node_contentroutes
node_profilepage -.->|"account actions"| node_authclient

click node_app "https://github.com/anujsomani/second-brain/blob/main/frontend/src/App.tsx"
click node_brainpage "https://github.com/anujsomani/second-brain/blob/main/frontend/src/pages/BrainPage.tsx"
click node_chatpage "https://github.com/anujsomani/second-brain/blob/main/frontend/src/pages/ChatPage.tsx"
click node_sharedpage "https://github.com/anujsomani/second-brain/blob/main/frontend/src/pages/SharedBrainPage.tsx"
click node_profilepage "https://github.com/anujsomani/second-brain/blob/main/frontend/src/pages/ProfilePage.tsx"
click node_authclient "https://github.com/anujsomani/second-brain/blob/main/frontend/src/lib/auth-api.ts"
click node_contentclient "https://github.com/anujsomani/second-brain/blob/main/frontend/src/lib/content-api.ts"
click node_authroutes "https://github.com/anujsomani/second-brain/blob/main/backend/src/auth.ts"
click node_oauth "https://github.com/anujsomani/second-brain/blob/main/backend/src/oauth.ts"
click node_userguard "https://github.com/anujsomani/second-brain/blob/main/backend/src/middlewares/user.ts"
click node_email "https://github.com/anujsomani/second-brain/blob/main/backend/src/sendEmail.ts"
click node_contentroutes "https://github.com/anujsomani/second-brain/blob/main/backend/src/content.ts"
click node_ingest "https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/ingest.ts"
click node_strategy "https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/detectExtractionStrategy.ts"
click node_extractors "https://github.com/anujsomani/second-brain/tree/main/backend/src/ai/extractor"
click node_metadata "https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/extractor/enhancedMetadata.ts"
click node_urlguard "https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/urlsafety.ts"
click node_chunker "https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/chunk.ts"
click node_embedding "https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/embedding.ts"
click node_retrieval "https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/retrieval.ts"
click node_chat "https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/chat.ts"
click node_llm "https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/llm.ts"
click node_db "https://github.com/anujsomani/second-brain/blob/main/backend/src/prisma.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_app,node_brainpage,node_chatpage,node_sharedpage,node_profilepage,node_authclient,node_contentclient,node_user toneBlue
class node_authroutes,node_oauth,node_userguard,node_email toneAmber
class node_contentroutes,node_ingest,node_strategy,node_extractors,node_metadata,node_urlguard,node_chunker toneMint
class node_embedding,node_retrieval,node_chat,node_llm toneRose
class node_db,node_gemini,node_resend toneIndigo
```

## Components

### Web client

- [Route application](https://github.com/anujsomani/second-brain/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Knowledge workspace](https://github.com/anujsomani/second-brain/blob/main/frontend/src/pages/BrainPage.tsx): `frontend/src/pages/BrainPage.tsx`
- [AI chat page](https://github.com/anujsomani/second-brain/blob/main/frontend/src/pages/ChatPage.tsx): `frontend/src/pages/ChatPage.tsx`
- [Shared brain page](https://github.com/anujsomani/second-brain/blob/main/frontend/src/pages/SharedBrainPage.tsx): `frontend/src/pages/SharedBrainPage.tsx`
- [Profile page](https://github.com/anujsomani/second-brain/blob/main/frontend/src/pages/ProfilePage.tsx): `frontend/src/pages/ProfilePage.tsx`
- [Account API client](https://github.com/anujsomani/second-brain/blob/main/frontend/src/lib/auth-api.ts): `frontend/src/lib/auth-api.ts`
- [Content API client](https://github.com/anujsomani/second-brain/blob/main/frontend/src/lib/content-api.ts): `frontend/src/lib/content-api.ts`

### Accounts and sharing

- [Authentication routes](https://github.com/anujsomani/second-brain/blob/main/backend/src/auth.ts): `backend/src/auth.ts`
- [Google OAuth](https://github.com/anujsomani/second-brain/blob/main/backend/src/oauth.ts): `backend/src/oauth.ts`
- [User middleware](https://github.com/anujsomani/second-brain/blob/main/backend/src/middlewares/user.ts): `backend/src/middlewares/user.ts`
- [Verification email](https://github.com/anujsomani/second-brain/blob/main/backend/src/sendEmail.ts): `backend/src/sendEmail.ts`

### Content management

- [Content routes](https://github.com/anujsomani/second-brain/blob/main/backend/src/content.ts): `backend/src/content.ts`
- [Content ingestion](https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/ingest.ts): `backend/src/ai/ingest.ts`
- [Extraction strategy](https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/detectExtractionStrategy.ts): `backend/src/ai/detectExtractionStrategy.ts`
- [Format extractors](https://github.com/anujsomani/second-brain/tree/main/backend/src/ai/extractor): `backend/src/ai/extractor`
- [Metadata extraction](https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/extractor/enhancedMetadata.ts): `backend/src/ai/extractor/enhancedMetadata.ts`
- [URL safety](https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/urlsafety.ts): `backend/src/ai/urlsafety.ts`
- [Text chunking](https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/chunk.ts): `backend/src/ai/chunk.ts`

### AI knowledge services

- [Gemini embeddings](https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/embedding.ts): `backend/src/ai/embedding.ts`
- [Vector retrieval](https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/retrieval.ts): `backend/src/ai/retrieval.ts`
- [Chat orchestration](https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/chat.ts): `backend/src/ai/chat.ts`
- [Answer generation](https://github.com/anujsomani/second-brain/blob/main/backend/src/ai/llm.ts): `backend/src/ai/llm.ts`

### Persistence

- [PostgreSQL database](https://github.com/anujsomani/second-brain/blob/main/backend/src/prisma.ts): `backend/src/prisma.ts`

### Other components

- **User**
- **Google Gemini**
- **Resend email**

## Connections

- User → Route application: uses (evidence: `frontend/src/App.tsx`)
- Route application → Knowledge workspace: routes to (evidence: `frontend/src/App.tsx`)
- Route application → AI chat page: routes to (evidence: `frontend/src/App.tsx`)
- Route application → Shared brain page: routes to (evidence: `frontend/src/App.tsx`)
- Route application → Profile page: routes to (evidence: `frontend/src/App.tsx`)
- Knowledge workspace → Content API client: fetches content (evidence: `frontend/src/pages/BrainPage.tsx`)
- Content API client → Content routes: HTTP requests
- Account API client → Authentication routes: HTTP requests
- Authentication routes → PostgreSQL database: reads and writes (evidence: `backend/src/auth.ts`)
- Authentication routes → Verification email: sends OTP (evidence: `backend/src/auth.ts`)
- Verification email → Resend email: sends email (evidence: `README.md`)
- Authentication routes → User middleware: guards logout (evidence: `backend/src/auth.ts`)
- Google OAuth → PostgreSQL database: reads and writes (evidence: `backend/src/oauth.ts`)
- Content routes → PostgreSQL database: manages content
- Content routes → Content ingestion: starts ingestion
- Content ingestion → PostgreSQL database: reads and writes (evidence: `backend/src/ai/ingest.ts`)
- Content ingestion → Extraction strategy: selects strategy (evidence: `backend/src/ai/ingest.ts`)
- Content ingestion → Format extractors: extracts content (evidence: `backend/src/ai/ingest.ts`)
- Content ingestion → Metadata extraction: extracts metadata (evidence: `backend/src/ai/ingest.ts`)
- Metadata extraction → URL safety: checks URLs (evidence: `backend/src/ai/extractor/enhancedMetadata.ts`)
- Content ingestion → Text chunking: chunks text (evidence: `backend/src/ai/ingest.ts`)
- Content ingestion → Gemini embeddings: embeds chunks (evidence: `backend/src/ai/ingest.ts`)
- Gemini embeddings → Google Gemini: requests embeddings (evidence: `backend/src/ai/embedding.ts`)
- Content ingestion → PostgreSQL database: stores vectors (evidence: `backend/src/ai/ingest.ts`)
- AI chat page → Chat orchestration: submits questions
- Chat orchestration → Vector retrieval: retrieves context
- Vector retrieval → Gemini embeddings: embeds query (evidence: `backend/src/ai/retrieval.ts`)
- Vector retrieval → PostgreSQL database: searches vectors (evidence: `backend/src/ai/retrieval.ts`)
- Chat orchestration → Answer generation: generates answer
- Answer generation → Google Gemini: generates response (evidence: `backend/src/ai/llm.ts`)
- Shared brain page → Content routes: loads shared brain
- Profile page → Account API client: account actions