# jacobinwwey/noteconnection architecture

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

- Interactive diagram: https://gitdiagram.com/jacobinwwey/noteconnection
- Repository: https://github.com/jacobinwwey/noteconnection

## Overview

NoteConnection turns local Markdown knowledge bases into navigable knowledge graphs, learning paths, and grounded answers. Its primary workflow is to select a knowledge-base folder, load and analyze its notes, then explore the resulting graph or ask scoped questions with source evidence. The graph also shows the learning and study-session domain, export, and Markdown-processing capabilities documented or represented in the repository. The README describes the RAG stages; sampled excerpts do not expose every runtime call between server, routes, storage, and learning modules, so uncertain links are omitted.

Main entry points: [`src/learning/KnowledgeLearningPlatform.ts`](https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/KnowledgeLearningPlatform.ts) (Learning runtime), [`src/core/Graph.ts`](https://github.com/jacobinwwey/noteconnection/blob/main/src/core/Graph.ts) (Knowledge graph), [`src/frontend/app.js`](https://github.com/jacobinwwey/noteconnection/blob/main/src/frontend/app.js) (Workspace interface), [`src/frontend/source_manager.js`](https://github.com/jacobinwwey/noteconnection/blob/main/src/frontend/source_manager.js) (Source loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Knowledge workspace"]
  node_frontend["Workspace interface<br/>[app.js]"]
  node_source["Source loading<br/>[source_manager.js]"]
  node_storage["Runtime storage"]
  node_server["Application server<br/>[server.ts]"]
end

subgraph group_graph["Graph analysis"]
  node_controller["Graph build entry<br/>[controller.ts]"]
  node_loader["File loading<br/>[FileLoader.ts]"]
  node_builder["Graph building<br/>[GraphBuilder.ts]"]
  node_graphmodel["Knowledge graph<br/>[Graph.ts]"]
  node_metrics["Graph analysis<br/>[GraphMetrics.ts]"]
  node_layout["Graph layout<br/>[LayoutEngine.ts]"]
  node_pathengine["Learning paths<br/>[PathEngine.ts]"]
end

subgraph group_learning["Learning and RAG"]
  node_learningapi["Learning runtime"]
  node_query["Knowledge retrieval<br/>[queryBackend.ts]"]
  node_context["Evidence assembly"]
  node_composer["Answer composition"]
  node_review["Grounding review"]
  node_mastery["Mastery and sessions<br/>[MasteryEngine.ts]"]
  node_export["Workspace export"]
end

subgraph group_content["Content services"]
  node_notemd["Markdown processing<br/>[NotemdService.ts]"]
  node_diagram["Diagram generation"]
  node_search["Web search providers<br/>[SearchManager.ts]"]
end

node_user(("Workspace user"))
node_markdown["Markdown knowledge base"]

node_user -->|"uses"| node_frontend
node_frontend -->|"loads notes"| node_source
node_source -->|"reads sources"| node_storage
node_markdown -->|"supplies notes"| node_storage
node_source -->|"requests build"| node_server
node_server -->|"triggers build"| node_controller
node_controller -->|"builds from files"| node_loader
node_loader -->|"provides notes"| node_builder
node_builder -->|"produces graph"| node_graphmodel
node_graphmodel -->|"analyzes structure"| node_metrics
node_graphmodel -->|"computes layout"| node_layout
node_graphmodel -->|"derives paths"| node_pathengine
node_frontend -->|"asks questions"| node_learningapi
node_learningapi -->|"retrieves evidence"| node_query
node_learningapi -->|"assembles graph context"| node_context
node_learningapi -->|"composes answer"| node_composer
node_learningapi -->|"reviews answer"| node_review
node_learningapi -->|"handles study requests"| node_mastery
node_learningapi -->|"exports workspace"| node_export
node_user -->|"requests processing"| node_notemd
node_notemd -->|"generates diagrams"| node_diagram
node_notemd -.->|"selects provider"| node_search

click node_frontend "https://github.com/jacobinwwey/noteconnection/blob/main/src/frontend/app.js"
click node_source "https://github.com/jacobinwwey/noteconnection/blob/main/src/frontend/source_manager.js"
click node_storage "https://github.com/jacobinwwey/noteconnection/blob/main/src/frontend/storage_provider.js"
click node_server "https://github.com/jacobinwwey/noteconnection/blob/main/src/server.ts"
click node_controller "https://github.com/jacobinwwey/noteconnection/blob/main/src/backend/controller.ts"
click node_loader "https://github.com/jacobinwwey/noteconnection/blob/main/src/backend/FileLoader.ts"
click node_builder "https://github.com/jacobinwwey/noteconnection/blob/main/src/backend/GraphBuilder.ts"
click node_graphmodel "https://github.com/jacobinwwey/noteconnection/blob/main/src/core/Graph.ts"
click node_metrics "https://github.com/jacobinwwey/noteconnection/blob/main/src/backend/GraphMetrics.ts"
click node_layout "https://github.com/jacobinwwey/noteconnection/blob/main/src/backend/algorithms/LayoutEngine.ts"
click node_pathengine "https://github.com/jacobinwwey/noteconnection/blob/main/src/core/PathEngine.ts"
click node_learningapi "https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/KnowledgeLearningPlatform.ts"
click node_query "https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/queryBackend.ts"
click node_context "https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/graphContextAssembler.ts"
click node_composer "https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/conversationComposer.ts"
click node_review "https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/answerReleaseReview.ts"
click node_mastery "https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/domains/MasteryEngine.ts"
click node_export "https://github.com/jacobinwwey/noteconnection/blob/main/src/export/WorkspaceExportBundle.ts"
click node_notemd "https://github.com/jacobinwwey/noteconnection/blob/main/src/notemd/NotemdService.ts"
click node_diagram "https://github.com/jacobinwwey/noteconnection/blob/main/src/notemd/diagram/diagramGenerationService.ts"
click node_search "https://github.com/jacobinwwey/noteconnection/blob/main/src/notemd/search/SearchManager.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_frontend,node_source,node_storage,node_server,node_user toneBlue
class node_controller,node_loader,node_builder,node_graphmodel,node_metrics,node_layout,node_pathengine toneAmber
class node_learningapi,node_query,node_context,node_composer,node_review,node_mastery,node_export toneMint
class node_notemd,node_diagram,node_search toneRose
class node_markdown toneIndigo
```

## Components

### Knowledge workspace

- [Workspace interface](https://github.com/jacobinwwey/noteconnection/blob/main/src/frontend/app.js): `src/frontend/app.js`
- [Source loading](https://github.com/jacobinwwey/noteconnection/blob/main/src/frontend/source_manager.js): `src/frontend/source_manager.js`
- [Runtime storage](https://github.com/jacobinwwey/noteconnection/blob/main/src/frontend/storage_provider.js): `src/frontend/storage_provider.js`
- [Application server](https://github.com/jacobinwwey/noteconnection/blob/main/src/server.ts): `src/server.ts`

### Graph analysis

- [Graph build entry](https://github.com/jacobinwwey/noteconnection/blob/main/src/backend/controller.ts): `src/backend/controller.ts`
- [File loading](https://github.com/jacobinwwey/noteconnection/blob/main/src/backend/FileLoader.ts): `src/backend/FileLoader.ts`
- [Graph building](https://github.com/jacobinwwey/noteconnection/blob/main/src/backend/GraphBuilder.ts): `src/backend/GraphBuilder.ts`
- [Knowledge graph](https://github.com/jacobinwwey/noteconnection/blob/main/src/core/Graph.ts): `src/core/Graph.ts`
- [Graph analysis](https://github.com/jacobinwwey/noteconnection/blob/main/src/backend/GraphMetrics.ts): `src/backend/GraphMetrics.ts`
- [Graph layout](https://github.com/jacobinwwey/noteconnection/blob/main/src/backend/algorithms/LayoutEngine.ts): `src/backend/algorithms/LayoutEngine.ts`
- [Learning paths](https://github.com/jacobinwwey/noteconnection/blob/main/src/core/PathEngine.ts): `src/core/PathEngine.ts`

### Learning and RAG

- [Learning runtime](https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/KnowledgeLearningPlatform.ts): `src/learning/KnowledgeLearningPlatform.ts`
- [Knowledge retrieval](https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/queryBackend.ts): `src/learning/queryBackend.ts`
- [Evidence assembly](https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/graphContextAssembler.ts): `src/learning/graphContextAssembler.ts`
- [Answer composition](https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/conversationComposer.ts): `src/learning/conversationComposer.ts`
- [Grounding review](https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/answerReleaseReview.ts): `src/learning/answerReleaseReview.ts`
- [Mastery and sessions](https://github.com/jacobinwwey/noteconnection/blob/main/src/learning/domains/MasteryEngine.ts): `src/learning/domains/MasteryEngine.ts`
- [Workspace export](https://github.com/jacobinwwey/noteconnection/blob/main/src/export/WorkspaceExportBundle.ts): `src/export/WorkspaceExportBundle.ts`

### Content services

- [Markdown processing](https://github.com/jacobinwwey/noteconnection/blob/main/src/notemd/NotemdService.ts): `src/notemd/NotemdService.ts`
- [Diagram generation](https://github.com/jacobinwwey/noteconnection/blob/main/src/notemd/diagram/diagramGenerationService.ts): `src/notemd/diagram/diagramGenerationService.ts`
- [Web search providers](https://github.com/jacobinwwey/noteconnection/blob/main/src/notemd/search/SearchManager.ts): `src/notemd/search/SearchManager.ts`

### Other components

- **Workspace user**
- **Markdown knowledge base**

## Connections

- Workspace user → Workspace interface: uses
- Workspace interface → Source loading: loads notes
- Source loading → Runtime storage: reads sources
- Markdown knowledge base → Runtime storage: supplies notes
- Source loading → Application server: requests build
- Application server → Graph build entry: triggers build
- Graph build entry → File loading: builds from files
- File loading → Graph building: provides notes
- Graph building → Knowledge graph: produces graph
- Knowledge graph → Graph analysis: analyzes structure
- Knowledge graph → Graph layout: computes layout
- Knowledge graph → Learning paths: derives paths
- Workspace interface → Learning runtime: asks questions
- Learning runtime → Knowledge retrieval: retrieves evidence
- Learning runtime → Evidence assembly: assembles graph context
- Learning runtime → Answer composition: composes answer
- Learning runtime → Grounding review: reviews answer
- Learning runtime → Mastery and sessions: handles study requests
- Learning runtime → Workspace export: exports workspace
- Workspace user → Markdown processing: requests processing
- Markdown processing → Diagram generation: generates diagrams
- Markdown processing → Web search providers: selects provider