# jorgepb96/nodus architecture

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

- Interactive diagram: https://gitdiagram.com/jorgepb96/nodus
- Repository: https://github.com/jorgepb96/nodus

## Overview

Nodus Research is a local-first desktop workspace for research, teaching, study, and structured data. Users work in focused vaults, bringing sources and materials into a workspace and using its research, learning, and data tools; the README also describes Zotero integration and optional online or local AI. The graph preserves those product areas and the sampled embedding, document-extraction, and database-research layers. Several domain implementations are represented by their exact directories because their source was not sampled; edges between those areas are omitted where the evidence does not establish runtime calls.

Main entry points: [`electron/main.ts`](https://github.com/jorgepb96/nodus/blob/main/electron/main.ts) (Nodus Desktop), [`electron/db/database.ts`](https://github.com/jorgepb96/nodus/blob/main/electron/db/database.ts) (Vault Database), [`electron/ai/embeddingPipeline.ts`](https://github.com/jorgepb96/nodus/blob/main/electron/ai/embeddingPipeline.ts) (Embedding Pipeline), [`electron/db/settingsRepo.ts`](https://github.com/jorgepb96/nodus/blob/main/electron/db/settingsRepo.ts) (Vault Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Desktop Workspace"]
  node_desktop["Nodus Desktop<br/>[main.ts]"]
  node_ui["Shared UI Components<br/>[ui.tsx]"]
  node_pipeline_logs["Pipeline Logging<br/>[pipelineLogCore.ts]"]
end

subgraph group_research["Research Work"]
  node_research_domain["Academic Research"]
  node_corpus["Library Extraction"]
  node_zotero["Zotero Integration"]
  node_family["Family Research"]
  node_structured_research["Database Research"]
end

subgraph group_learning["Teaching And Study"]
  node_teaching["Teaching Tools<br/>[teachingRubrics.ts]"]
  node_study["Study Tools<br/>[studyAssistant.ts]"]
end

subgraph group_data["Vault Data"]
  node_database_ui["Database Workspace"]
  node_sqlite[("Vault Database<br/>[database.ts]")]
  node_ideas["Ideas Repository<br/>[ideasRepo.ts]"]
  node_settings["Vault Settings<br/>[settingsRepo.ts]"]
  node_embedding_repo[("Embedding Index Store")]
end

subgraph group_intelligence["AI And Search"]
  node_embedding_pipeline["Embedding Pipeline"]
  node_ai_client["AI Client<br/>[aiClient.ts]"]
  node_local_ai["Local AI<br/>[nodusLocalAi.ts]"]
  node_provenance["Embedding Provenance"]
end

node_user(("Researcher Or Learner"))

node_user -->|"uses"| node_desktop
node_desktop -->|"offers research"| node_research_domain
node_desktop -->|"offers genealogy"| node_family
node_desktop -->|"offers databases"| node_database_ui
node_desktop -->|"offers teaching"| node_teaching
node_desktop -->|"offers study"| node_study
node_research_domain -.->|"integrates Zotero"| node_zotero
node_corpus -.->|"uses storage"| node_sqlite
node_embedding_pipeline -->|"requests embeddings"| node_ai_client
node_embedding_pipeline -->|"reads and writes"| node_sqlite
node_embedding_pipeline -->|"reads idea text"| node_ideas
node_embedding_pipeline -->|"reads configuration"| node_settings
node_settings -->|"uses database"| node_sqlite
node_settings -->|"loads index state"| node_embedding_repo
node_ideas -->|"uses database"| node_sqlite
node_structured_research -->|"loads research state"| node_sqlite
node_ai_client -->|"reads settings"| node_settings
node_ai_client -.->|"supports local models"| node_local_ai

click node_desktop "https://github.com/jorgepb96/nodus/blob/main/electron/main.ts"
click node_ui "https://github.com/jorgepb96/nodus/blob/main/src/components/ui.tsx"
click node_research_domain "https://github.com/jorgepb96/nodus/tree/main/electron/ai"
click node_corpus "https://github.com/jorgepb96/nodus/blob/main/electron/library/libraryExtractionEngine.ts"
click node_zotero "https://github.com/jorgepb96/nodus/tree/main/electron/zotero"
click node_family "https://github.com/jorgepb96/nodus/blob/main/electron/ai/genealogyDeepResearch.ts"
click node_structured_research "https://github.com/jorgepb96/nodus/blob/main/shared/databaseResearchEngine.ts"
click node_teaching "https://github.com/jorgepb96/nodus/blob/main/electron/ai/teachingRubrics.ts"
click node_study "https://github.com/jorgepb96/nodus/blob/main/electron/ai/studyAssistant.ts"
click node_database_ui "https://github.com/jorgepb96/nodus/tree/main/electron/db"
click node_sqlite "https://github.com/jorgepb96/nodus/blob/main/electron/db/database.ts"
click node_ideas "https://github.com/jorgepb96/nodus/blob/main/electron/db/ideasRepo.ts"
click node_settings "https://github.com/jorgepb96/nodus/blob/main/electron/db/settingsRepo.ts"
click node_embedding_repo "https://github.com/jorgepb96/nodus/blob/main/electron/db/embeddingIndexesRepo.ts"
click node_embedding_pipeline "https://github.com/jorgepb96/nodus/blob/main/electron/ai/embeddingPipeline.ts"
click node_ai_client "https://github.com/jorgepb96/nodus/blob/main/electron/ai/aiClient.ts"
click node_local_ai "https://github.com/jorgepb96/nodus/blob/main/electron/ai/nodusLocalAi.ts"
click node_provenance "https://github.com/jorgepb96/nodus/blob/main/electron/ai/embeddingProvenance.ts"
click node_pipeline_logs "https://github.com/jorgepb96/nodus/blob/main/electron/logging/pipelineLogCore.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_desktop,node_ui,node_pipeline_logs toneBlue
class node_research_domain,node_corpus,node_zotero,node_family,node_structured_research toneAmber
class node_teaching,node_study toneMint
class node_database_ui,node_sqlite,node_ideas,node_settings,node_embedding_repo toneRose
class node_embedding_pipeline,node_ai_client,node_local_ai,node_provenance,node_user toneIndigo
```

## Components

### Desktop Workspace

- [Nodus Desktop](https://github.com/jorgepb96/nodus/blob/main/electron/main.ts): `electron/main.ts`
- [Shared UI Components](https://github.com/jorgepb96/nodus/blob/main/src/components/ui.tsx): `src/components/ui.tsx`
- [Pipeline Logging](https://github.com/jorgepb96/nodus/blob/main/electron/logging/pipelineLogCore.ts): `electron/logging/pipelineLogCore.ts`

### Research Work

- [Academic Research](https://github.com/jorgepb96/nodus/tree/main/electron/ai): `electron/ai`
- [Library Extraction](https://github.com/jorgepb96/nodus/blob/main/electron/library/libraryExtractionEngine.ts): `electron/library/libraryExtractionEngine.ts`
- [Zotero Integration](https://github.com/jorgepb96/nodus/tree/main/electron/zotero): `electron/zotero`
- [Family Research](https://github.com/jorgepb96/nodus/blob/main/electron/ai/genealogyDeepResearch.ts): `electron/ai/genealogyDeepResearch.ts`
- [Database Research](https://github.com/jorgepb96/nodus/blob/main/shared/databaseResearchEngine.ts): `shared/databaseResearchEngine.ts`

### Teaching And Study

- [Teaching Tools](https://github.com/jorgepb96/nodus/blob/main/electron/ai/teachingRubrics.ts): `electron/ai/teachingRubrics.ts`
- [Study Tools](https://github.com/jorgepb96/nodus/blob/main/electron/ai/studyAssistant.ts): `electron/ai/studyAssistant.ts`

### Vault Data

- [Database Workspace](https://github.com/jorgepb96/nodus/tree/main/electron/db): `electron/db`
- [Vault Database](https://github.com/jorgepb96/nodus/blob/main/electron/db/database.ts): `electron/db/database.ts`
- [Ideas Repository](https://github.com/jorgepb96/nodus/blob/main/electron/db/ideasRepo.ts): `electron/db/ideasRepo.ts`
- [Vault Settings](https://github.com/jorgepb96/nodus/blob/main/electron/db/settingsRepo.ts): `electron/db/settingsRepo.ts`
- [Embedding Index Store](https://github.com/jorgepb96/nodus/blob/main/electron/db/embeddingIndexesRepo.ts): `electron/db/embeddingIndexesRepo.ts`

### AI And Search

- [Embedding Pipeline](https://github.com/jorgepb96/nodus/blob/main/electron/ai/embeddingPipeline.ts): `electron/ai/embeddingPipeline.ts`
- [AI Client](https://github.com/jorgepb96/nodus/blob/main/electron/ai/aiClient.ts): `electron/ai/aiClient.ts`
- [Local AI](https://github.com/jorgepb96/nodus/blob/main/electron/ai/nodusLocalAi.ts): `electron/ai/nodusLocalAi.ts`
- [Embedding Provenance](https://github.com/jorgepb96/nodus/blob/main/electron/ai/embeddingProvenance.ts): `electron/ai/embeddingProvenance.ts`

### Other components

- **Researcher Or Learner**

## Connections

- Researcher Or Learner → Nodus Desktop: uses (evidence: `README.md`)
- Nodus Desktop → Academic Research: offers research (evidence: `README.md`)
- Nodus Desktop → Family Research: offers genealogy (evidence: `README.md`)
- Nodus Desktop → Database Workspace: offers databases (evidence: `README.md`)
- Nodus Desktop → Teaching Tools: offers teaching (evidence: `README.md`)
- Nodus Desktop → Study Tools: offers study (evidence: `README.md`)
- Academic Research → Zotero Integration: integrates Zotero (evidence: `README.md`)
- Library Extraction → Vault Database: uses storage
- Embedding Pipeline → AI Client: requests embeddings (evidence: `electron/ai/embeddingPipeline.ts`)
- Embedding Pipeline → Vault Database: reads and writes (evidence: `electron/ai/embeddingPipeline.ts`)
- Embedding Pipeline → Ideas Repository: reads idea text (evidence: `electron/ai/embeddingPipeline.ts`)
- Embedding Pipeline → Vault Settings: reads configuration (evidence: `electron/ai/embeddingPipeline.ts`)
- Vault Settings → Vault Database: uses database (evidence: `electron/db/settingsRepo.ts`)
- Vault Settings → Embedding Index Store: loads index state (evidence: `electron/db/settingsRepo.ts`)
- Ideas Repository → Vault Database: uses database (evidence: `electron/db/ideasRepo.ts`)
- Database Research → Vault Database: loads research state (evidence: `shared/databaseResearchEngine.ts`)
- AI Client → Vault Settings: reads settings (evidence: `electron/ai/aiClient.ts`)
- AI Client → Local AI: supports local models (evidence: `electron/ai/aiClient.ts`)
