# i-junaidkhan/notebook_llm architecture

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

- Interactive diagram: https://gitdiagram.com/i-junaidkhan/notebook_llm
- Repository: https://github.com/i-junaidkhan/notebook_llm

## Overview

CogniFlow is a privacy-first research and knowledge platform: users collect sources, organize them into notebooks, then search or ask questions and synthesize findings into notes, transformations, mind maps, and podcasts. The backend exposes these capabilities through FastAPI routes, with LangGraph workflows and domain services using SurrealDB and configurable AI models. The graph preserves documented product branches, but several are represented at their exact enclosing directories because their implementation was not sampled; those links are marked unverified rather than inferred as confirmed calls.

Main entry points: [`api/routers`](https://github.com/i-junaidkhan/notebook_llm/tree/main/api/routers) (Feature routes), [`open_notebook/database/repository.py`](https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/database/repository.py) (SurrealDB repository), [`open_notebook/domain/notebook.py`](https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/domain/notebook.py) (Notebooks and notes), [`api/routers/chat.py`](https://github.com/i-junaidkhan/notebook_llm/blob/main/api/routers/chat.py) (Knowledge chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web application"]
end

subgraph group_api["API and services"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_routes["Feature routes"]
  node_api_services["API services"]
end

subgraph group_knowledge["Knowledge workflows"]
  node_source_ingest["Source ingestion<br/>[sources_service.py]"]
  node_notebooks["Notebooks and notes<br/>[notebook.py]"]
  node_chat["Knowledge chat<br/>[chat.py]"]
  node_source_chat["Source chat<br/>[source_chat.py]"]
  node_context["Context assembly<br/>[context_builder.py]"]
  node_search_ask["Search and ask<br/>[search.py]"]
  node_transformations["Transformations"]
  node_mind_maps["Mind maps"]
  node_podcasts["Podcast generation<br/>[podcast_service.py]"]
  node_embedding_jobs["Embedding jobs"]
end

subgraph group_platform["Models and storage"]
  node_embedding_utils["Embedding utilities<br/>[embedding.py]"]
  node_models["AI model manager<br/>[models.py]"]
  node_domain["Domain records"]
  node_repository[("SurrealDB repository<br/>[repository.py]")]
end

node_user(("Researcher"))
node_surrealdb[("SurrealDB")]
node_ai_providers{{"AI providers"}}

node_user -.->|"uses"| node_web
node_web -.->|"requests"| node_api_app
node_api_app -->|"registers"| node_routes
node_routes -.->|"delegates"| node_api_services
node_routes -.->|"ingests"| node_source_ingest
node_routes -.->|"manages"| node_notebooks
node_routes -->|"routes chat"| node_chat
node_chat -->|"loads records"| node_notebooks
node_chat -.->|"uses context"| node_context
node_chat -->|"queries"| node_repository
node_routes -->|"routes chat"| node_source_chat
node_source_chat -->|"builds context"| node_context
node_routes -->|"routes search"| node_search_ask
node_search_ask -->|"loads records"| node_notebooks
node_search_ask -->|"selects models"| node_models
node_search_ask -.->|"searches records"| node_repository
node_routes -.->|"applies patterns"| node_transformations
node_routes -.->|"generates maps"| node_mind_maps
node_routes -.->|"generates audio"| node_podcasts
node_routes -->|"submits jobs"| node_embedding_jobs
node_embedding_jobs -->|"loads content"| node_notebooks
node_embedding_jobs -->|"generates vectors"| node_embedding_utils
node_embedding_utils -->|"embeds text"| node_models
node_embedding_utils -.->|"stores vectors"| node_repository
node_models -->|"loads configuration"| node_repository
node_models -.->|"creates models"| node_ai_providers
node_notebooks -->|"persists records"| node_repository
node_domain -->|"uses persistence"| node_repository
node_repository -->|"queries"| node_surrealdb

click node_web "https://github.com/i-junaidkhan/notebook_llm/tree/main/frontend/src/app"
click node_api_app "https://github.com/i-junaidkhan/notebook_llm/blob/main/api/main.py"
click node_routes "https://github.com/i-junaidkhan/notebook_llm/tree/main/api/routers"
click node_api_services "https://github.com/i-junaidkhan/notebook_llm/tree/main/api"
click node_source_ingest "https://github.com/i-junaidkhan/notebook_llm/blob/main/api/sources_service.py"
click node_notebooks "https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/domain/notebook.py"
click node_chat "https://github.com/i-junaidkhan/notebook_llm/blob/main/api/routers/chat.py"
click node_source_chat "https://github.com/i-junaidkhan/notebook_llm/blob/main/api/routers/source_chat.py"
click node_context "https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/utils/context_builder.py"
click node_search_ask "https://github.com/i-junaidkhan/notebook_llm/blob/main/api/routers/search.py"
click node_transformations "https://github.com/i-junaidkhan/notebook_llm/blob/main/api/transformations_service.py"
click node_mind_maps "https://github.com/i-junaidkhan/notebook_llm/tree/main/open_notebook/graphs"
click node_podcasts "https://github.com/i-junaidkhan/notebook_llm/blob/main/api/podcast_service.py"
click node_embedding_jobs "https://github.com/i-junaidkhan/notebook_llm/blob/main/commands/embedding_commands.py"
click node_embedding_utils "https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/utils/embedding.py"
click node_models "https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/ai/models.py"
click node_domain "https://github.com/i-junaidkhan/notebook_llm/tree/main/open_notebook/domain"
click node_repository "https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/database/repository.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 toneBlue
class node_api_app,node_routes,node_api_services,node_surrealdb toneAmber
class node_source_ingest,node_notebooks,node_chat,node_source_chat,node_context,node_search_ask,node_transformations,node_mind_maps,node_podcasts,node_embedding_jobs toneMint
class node_embedding_utils,node_models,node_domain,node_repository toneRose
class node_user,node_ai_providers toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/i-junaidkhan/notebook_llm/tree/main/frontend/src/app): `frontend/src/app`

### API and services

- [FastAPI application](https://github.com/i-junaidkhan/notebook_llm/blob/main/api/main.py): `api/main.py`
- [Feature routes](https://github.com/i-junaidkhan/notebook_llm/tree/main/api/routers): `api/routers`
- [API services](https://github.com/i-junaidkhan/notebook_llm/tree/main/api): `api`

### Knowledge workflows

- [Source ingestion](https://github.com/i-junaidkhan/notebook_llm/blob/main/api/sources_service.py): `api/sources_service.py`
- [Notebooks and notes](https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/domain/notebook.py): `open_notebook/domain/notebook.py`
- [Knowledge chat](https://github.com/i-junaidkhan/notebook_llm/blob/main/api/routers/chat.py): `api/routers/chat.py`
- [Source chat](https://github.com/i-junaidkhan/notebook_llm/blob/main/api/routers/source_chat.py): `api/routers/source_chat.py`
- [Context assembly](https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/utils/context_builder.py): `open_notebook/utils/context_builder.py`
- [Search and ask](https://github.com/i-junaidkhan/notebook_llm/blob/main/api/routers/search.py): `api/routers/search.py`
- [Transformations](https://github.com/i-junaidkhan/notebook_llm/blob/main/api/transformations_service.py): `api/transformations_service.py`
- [Mind maps](https://github.com/i-junaidkhan/notebook_llm/tree/main/open_notebook/graphs): `open_notebook/graphs`
- [Podcast generation](https://github.com/i-junaidkhan/notebook_llm/blob/main/api/podcast_service.py): `api/podcast_service.py`
- [Embedding jobs](https://github.com/i-junaidkhan/notebook_llm/blob/main/commands/embedding_commands.py): `commands/embedding_commands.py`

### Models and storage

- [Embedding utilities](https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/utils/embedding.py): `open_notebook/utils/embedding.py`
- [AI model manager](https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/ai/models.py): `open_notebook/ai/models.py`
- [Domain records](https://github.com/i-junaidkhan/notebook_llm/tree/main/open_notebook/domain): `open_notebook/domain`
- [SurrealDB repository](https://github.com/i-junaidkhan/notebook_llm/blob/main/open_notebook/database/repository.py): `open_notebook/database/repository.py`

### Other components

- **Researcher**
- **SurrealDB**
- **AI providers**

## Connections

- Researcher → Web application: uses
- Web application → FastAPI application: requests
- FastAPI application → Feature routes: registers (evidence: `api/main.py`)
- Feature routes → API services: delegates (evidence: `api/routers/embedding_rebuild.py`)
- Feature routes → Source ingestion: ingests
- Feature routes → Notebooks and notes: manages (evidence: `api/routers/embedding.py`)
- Feature routes → Knowledge chat: routes chat (evidence: `api/main.py`)
- Knowledge chat → Notebooks and notes: loads records (evidence: `api/routers/chat.py`)
- Knowledge chat → Context assembly: uses context
- Knowledge chat → SurrealDB repository: queries (evidence: `api/routers/chat.py`)
- Feature routes → Source chat: routes chat (evidence: `api/main.py`)
- Source chat → Context assembly: builds context
- Feature routes → Search and ask: routes search (evidence: `api/main.py`)
- Search and ask → Notebooks and notes: loads records (evidence: `api/routers/search.py`)
- Search and ask → AI model manager: selects models (evidence: `api/routers/search.py`)
- Search and ask → SurrealDB repository: searches records
- Feature routes → Transformations: applies patterns
- Feature routes → Mind maps: generates maps (evidence: `api/routers/search.py`)
- Feature routes → Podcast generation: generates audio
- Feature routes → Embedding jobs: submits jobs (evidence: `api/routers/embedding.py`)
- Embedding jobs → Notebooks and notes: loads content (evidence: `commands/embedding_commands.py`)
- Embedding jobs → Embedding utilities: generates vectors (evidence: `commands/embedding_commands.py`)
- Embedding utilities → AI model manager: embeds text (evidence: `open_notebook/utils/embedding.py`)
- Embedding utilities → SurrealDB repository: stores vectors
- AI model manager → SurrealDB repository: loads configuration (evidence: `open_notebook/ai/models.py`)
- AI model manager → AI providers: creates models
- Notebooks and notes → SurrealDB repository: persists records (evidence: `open_notebook/domain/notebook.py`)
- Domain records → SurrealDB repository: uses persistence (evidence: `open_notebook/domain/base.py`)
- SurrealDB repository → SurrealDB: queries (evidence: `open_notebook/database/repository.py`)