# sriharirajukanumuriflorida/second-brain architecture

> Architecture diagram of the GitHub repository sriharirajukanumuriflorida/second-brain, 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/sriharirajukanumuriflorida/second-brain
- Repository: https://github.com/sriharirajukanumuriflorida/second-brain

## Overview

Second Brain is a read-only Obsidian-vault knowledge platform: GitHub vault content is synced and indexed, then users browse notes, search, check status, or chat over their knowledge. GitHub OAuth protects owner actions; temporary share links provide separate read-only access. The graph includes the frontend, API, ingestion/search, auth, and persistence layers. Several subsystem links rely on README or SOURCE INDEX references because their implementation files were not excerpted; those limits are reflected in the evidence paths.

Main entry points: [`backend/app/main.py`](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/models.py`](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/models.py) (Vault and session records), [`frontend/src/App.jsx`](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/App.jsx) (React application), [`frontend/src/api/client.js`](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/api/client.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web application"]
  node_web["React application<br/>[App.jsx]"]
  node_web_api["API client<br/>[client.js]"]
  node_web_auth["Auth client<br/>[auth.js]"]
  node_pages["Notes and search UI<br/>[SearchPage.jsx]"]
  node_chat_ui["Chat UI<br/>[ChatPage.jsx]"]
  node_admin_ui["Admin UI<br/>[AdminPage.jsx]"]
end

subgraph group_api["API and access"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_notes["Notes and status API<br/>[notes.py]"]
  node_api_sync["Sync API<br/>[sync.py]"]
  node_api_search["Search API<br/>[search.py]"]
  node_api_chat["Chat API<br/>[chat.py]"]
  node_api_auth["OAuth and sessions<br/>[auth.py]"]
  node_api_access["Share-link access<br/>[access.py]"]
  node_auth_services["Auth services<br/>[session_service.py]"]
end

subgraph group_knowledge["Vault and knowledge"]
  node_github["GitHub vault"]
  node_sync_index["Vault sync and indexing<br/>[index_service.py]"]
  node_parse_extract["Markdown parsing<br/>[parser_service.py]"]
  node_embeddings["Embedding generation"]
end

subgraph group_assistant["Search and chat"]
  node_hybrid["Hybrid search<br/>[hybrid_search.py]"]
  node_workflows["Agent workflows"]
  node_llm["LLM providers<br/>[factory.py]"]
end

subgraph group_persistence["Persistence"]
  node_db_models["Vault and session records<br/>[models.py]"]
  node_database[("Application database<br/>[database.py]")]
end

node_visitor(("Owner or visitor"))
node_github_oauth["GitHub OAuth"]

node_visitor -->|"uses"| node_web
node_web -->|"routes to"| node_pages
node_web -->|"routes to"| node_chat_ui
node_web -->|"routes to"| node_admin_ui
node_pages -->|"requests data"| node_web_api
node_chat_ui -->|"requests chat"| node_web_api
node_admin_ui -->|"requests admin actions"| node_web_api
node_web_api -->|"calls API"| node_api_app
node_web_auth -.->|"handles login"| node_api_auth
node_api_app -->|"registers router"| node_api_notes
node_api_app -->|"registers router"| node_api_sync
node_api_app -->|"registers router"| node_api_search
node_api_app -->|"registers router"| node_api_chat
node_api_app -->|"registers router"| node_api_auth
node_api_app -->|"registers router"| node_api_access
node_api_sync -->|"syncs vault"| node_github
node_api_sync -.->|"starts indexing"| node_sync_index
node_sync_index -.->|"parses notes"| node_parse_extract
node_sync_index -.->|"indexes metadata"| node_db_models
node_api_search -.->|"searches notes"| node_hybrid
node_api_chat -->|"dispatches chat"| node_workflows
node_workflows -.->|"retrieves context"| node_hybrid
node_workflows -.->|"generates response"| node_llm
node_api_chat -->|"selects provider"| node_llm
node_api_auth -->|"manages sessions"| node_auth_services
node_api_access -->|"checks access"| node_auth_services
node_auth_services -->|"reads and writes"| node_db_models
node_embeddings -->|"stores chunks"| node_db_models
node_hybrid -->|"queries indexed notes"| node_db_models
node_database -->|"backs models"| node_db_models
node_api_notes -.->|"uses sessions"| node_database
node_github_oauth -->|"authorizes login"| node_api_auth

click node_web "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/App.jsx"
click node_web_api "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/api/client.js"
click node_web_auth "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/api/auth.js"
click node_pages "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/pages/SearchPage.jsx"
click node_chat_ui "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/pages/ChatPage.jsx"
click node_admin_ui "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/pages/AdminPage.jsx"
click node_api_app "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/main.py"
click node_api_notes "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/notes.py"
click node_api_sync "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/sync.py"
click node_api_search "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/search.py"
click node_api_chat "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/chat.py"
click node_api_auth "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/auth.py"
click node_api_access "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/access.py"
click node_sync_index "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/index_service.py"
click node_parse_extract "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/parser_service.py"
click node_embeddings "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/embeddings/embedding_service.py"
click node_hybrid "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/search/hybrid_search.py"
click node_workflows "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/workflows/mentor_chat_workflow.py"
click node_llm "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/llm/factory.py"
click node_auth_services "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/auth/session_service.py"
click node_db_models "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/models.py"
click node_database "https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/database.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_api,node_web_auth,node_pages,node_chat_ui,node_admin_ui toneBlue
class node_api_app,node_api_notes,node_api_sync,node_api_search,node_api_chat,node_api_auth,node_api_access,node_auth_services toneAmber
class node_github,node_sync_index,node_parse_extract,node_embeddings toneMint
class node_hybrid,node_workflows,node_llm toneRose
class node_db_models,node_database,node_visitor,node_github_oauth toneIndigo
```

## Components

### Web application

- [React application](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Auth client](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/api/auth.js): `frontend/src/api/auth.js`
- [Notes and search UI](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/pages/SearchPage.jsx): `frontend/src/pages/SearchPage.jsx`
- [Chat UI](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/pages/ChatPage.jsx): `frontend/src/pages/ChatPage.jsx`
- [Admin UI](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/frontend/src/pages/AdminPage.jsx): `frontend/src/pages/AdminPage.jsx`

### API and access

- [FastAPI application](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/main.py): `backend/app/main.py`
- [Notes and status API](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/notes.py): `backend/app/api/notes.py`
- [Sync API](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/sync.py): `backend/app/api/sync.py`
- [Search API](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/search.py): `backend/app/api/search.py`
- [Chat API](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [OAuth and sessions](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Share-link access](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/api/access.py): `backend/app/api/access.py`
- [Auth services](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/auth/session_service.py): `backend/app/services/auth/session_service.py`

### Vault and knowledge

- **GitHub vault**
- [Vault sync and indexing](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/index_service.py): `backend/app/services/index_service.py`
- [Markdown parsing](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/parser_service.py): `backend/app/services/parser_service.py`
- [Embedding generation](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/embeddings/embedding_service.py): `backend/app/services/embeddings/embedding_service.py`

### Search and chat

- [Hybrid search](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/search/hybrid_search.py): `backend/app/services/search/hybrid_search.py`
- [Agent workflows](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/workflows/mentor_chat_workflow.py): `backend/app/services/workflows/mentor_chat_workflow.py`
- [LLM providers](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/services/llm/factory.py): `backend/app/services/llm/factory.py`

### Persistence

- [Vault and session records](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/models.py): `backend/app/models.py`
- [Application database](https://github.com/sriharirajukanumuriflorida/second-brain/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Owner or visitor**
- **GitHub OAuth**

## Connections

- Owner or visitor → React application: uses (evidence: `README.md`)
- React application → Notes and search UI: routes to (evidence: `frontend/src/App.jsx`)
- React application → Chat UI: routes to (evidence: `frontend/src/App.jsx`)
- React application → Admin UI: routes to (evidence: `frontend/src/App.jsx`)
- Notes and search UI → API client: requests data (evidence: `frontend/src/pages/SearchPage.jsx`)
- Chat UI → API client: requests chat (evidence: `frontend/src/pages/ChatPage.jsx`)
- Admin UI → API client: requests admin actions (evidence: `frontend/src/pages/AdminPage.jsx`)
- API client → FastAPI application: calls API (evidence: `frontend/src/api/client.js`)
- Auth client → OAuth and sessions: handles login (evidence: `frontend/src/api/auth.js`)
- FastAPI application → Notes and status API: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Sync API: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Search API: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Chat API: registers router (evidence: `backend/app/main.py`)
- FastAPI application → OAuth and sessions: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Share-link access: registers router (evidence: `backend/app/main.py`)
- Sync API → GitHub vault: syncs vault (evidence: `README.md`)
- Sync API → Vault sync and indexing: starts indexing
- Vault sync and indexing → Markdown parsing: parses notes
- Vault sync and indexing → Vault and session records: indexes metadata
- Search API → Hybrid search: searches notes
- Chat API → Agent workflows: dispatches chat (evidence: `backend/app/api/chat.py`)
- Agent workflows → Hybrid search: retrieves context
- Agent workflows → LLM providers: generates response
- Chat API → LLM providers: selects provider (evidence: `backend/app/api/chat.py`)
- OAuth and sessions → Auth services: manages sessions (evidence: `backend/app/api/auth.py`)
- Share-link access → Auth services: checks access (evidence: `backend/app/api/access.py`)
- Auth services → Vault and session records: reads and writes (evidence: `backend/app/services/auth/session_service.py`)
- Embedding generation → Vault and session records: stores chunks (evidence: `backend/app/services/embeddings/embedding_service.py`)
- Hybrid search → Vault and session records: queries indexed notes (evidence: `backend/app/services/search/hybrid_search.py`)
- Application database → Vault and session records: backs models (evidence: `backend/app/models.py`)
- Notes and status API → Application database: uses sessions
- GitHub OAuth → OAuth and sessions: authorizes login
