# gamosoft/notediscovery architecture

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

- Interactive diagram: https://gitdiagram.com/gamosoft/notediscovery
- Repository: https://github.com/gamosoft/notediscovery

## Overview

NoteDiscovery is a self-hosted Markdown knowledge base. Users write and organize notes in the web app, which communicates with the FastAPI backend and stores notes as files; discovery features include search, tags, backlinks, and a knowledge graph. AI clients can also access notes through the MCP server and its HTTP client. The graph preserves README capabilities such as sharing, export, drawing, themes, and plugins. Some feature-specific implementation paths are not shown, so their placement and connections are omitted where evidence is insufficient.

Main entry points: [`backend/main.py`](https://github.com/gamosoft/notediscovery/blob/main/backend/main.py) (FastAPI application), [`mcp_server/server.py`](https://github.com/gamosoft/notediscovery/blob/main/mcp_server/server.py) (MCP server), [`frontend/app.js`](https://github.com/gamosoft/notediscovery/blob/main/frontend/app.js) (Web app), [`backend/utils.py`](https://github.com/gamosoft/notediscovery/blob/main/backend/utils.py) (File and Markdown utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web app<br/>[app.js]"]
  node_themes["Theme management<br/>[themes.py]"]
end

subgraph group_backend["Note services"]
  node_api["FastAPI application<br/>[main.py]"]
  node_note_files[("Markdown storage")]
  node_file_utils["File and Markdown utilities<br/>[utils.py]"]
  node_sharing["Public sharing<br/>[share.py]"]
  node_export["HTML export<br/>[export.py]"]
end

subgraph group_discovery["Note discovery"]
  node_index[("Note index<br/>[note_index.py]")]
  node_search["Search and navigation<br/>[utils.py]"]
  node_graph["Links and graph<br/>[note_index.py]"]
end

subgraph group_extensions["Extensions"]
  node_plugins["Plugin system<br/>[plugins.py]"]
  node_plugin_addons["Plugin extensions"]
end

subgraph group_mcp["AI integration"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_mcp_tools["MCP tools<br/>[tools.py]"]
  node_mcp_client["HTTP API client<br/>[client.py]"]
  node_mcp_config["MCP configuration<br/>[config.py]"]
end

node_user(("User"))
node_mcp_user(("AI assistant"))

node_user -->|"uses"| node_webapp
node_webapp -.->|"requests data"| node_api
node_api -->|"reads notes"| node_note_files
node_api -->|"calls"| node_file_utils
node_file_utils -->|"uses extraction"| node_index
node_api -->|"dispatches hooks"| node_plugins
node_api -.->|"serves discovery"| node_search
node_api -.->|"serves graph"| node_graph
node_api -.->|"handles sharing"| node_sharing
node_api -.->|"handles export"| node_export
node_api -.->|"serves themes"| node_themes
node_plugins -.->|"loads extensions"| node_plugin_addons
node_mcp_user -->|"requests note actions"| node_mcp_server
node_mcp_server -->|"calls"| node_mcp_client
node_mcp_server -->|"uses definitions"| node_mcp_tools
node_mcp_server -->|"loads settings"| node_mcp_config
node_mcp_client -->|"sends HTTP requests"| node_api

click node_webapp "https://github.com/gamosoft/notediscovery/blob/main/frontend/app.js"
click node_api "https://github.com/gamosoft/notediscovery/blob/main/backend/main.py"
click node_file_utils "https://github.com/gamosoft/notediscovery/blob/main/backend/utils.py"
click node_index "https://github.com/gamosoft/notediscovery/blob/main/backend/note_index.py"
click node_search "https://github.com/gamosoft/notediscovery/blob/main/backend/utils.py"
click node_graph "https://github.com/gamosoft/notediscovery/blob/main/backend/note_index.py"
click node_sharing "https://github.com/gamosoft/notediscovery/blob/main/backend/share.py"
click node_export "https://github.com/gamosoft/notediscovery/blob/main/backend/export.py"
click node_themes "https://github.com/gamosoft/notediscovery/blob/main/backend/themes.py"
click node_plugins "https://github.com/gamosoft/notediscovery/blob/main/backend/plugins.py"
click node_plugin_addons "https://github.com/gamosoft/notediscovery/tree/main/plugins"
click node_mcp_server "https://github.com/gamosoft/notediscovery/blob/main/mcp_server/server.py"
click node_mcp_tools "https://github.com/gamosoft/notediscovery/blob/main/mcp_server/tools.py"
click node_mcp_client "https://github.com/gamosoft/notediscovery/blob/main/mcp_server/client.py"
click node_mcp_config "https://github.com/gamosoft/notediscovery/blob/main/mcp_server/config.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_webapp,node_themes,node_user toneBlue
class node_api,node_note_files,node_file_utils,node_sharing,node_export toneAmber
class node_index,node_search,node_graph toneMint
class node_plugins,node_plugin_addons toneRose
class node_mcp_server,node_mcp_tools,node_mcp_client,node_mcp_config,node_mcp_user toneIndigo
```

## Components

### Web experience

- [Web app](https://github.com/gamosoft/notediscovery/blob/main/frontend/app.js): `frontend/app.js`
- [Theme management](https://github.com/gamosoft/notediscovery/blob/main/backend/themes.py): `backend/themes.py`

### Note services

- [FastAPI application](https://github.com/gamosoft/notediscovery/blob/main/backend/main.py): `backend/main.py`
- **Markdown storage**
- [File and Markdown utilities](https://github.com/gamosoft/notediscovery/blob/main/backend/utils.py): `backend/utils.py`
- [Public sharing](https://github.com/gamosoft/notediscovery/blob/main/backend/share.py): `backend/share.py`
- [HTML export](https://github.com/gamosoft/notediscovery/blob/main/backend/export.py): `backend/export.py`

### Note discovery

- [Note index](https://github.com/gamosoft/notediscovery/blob/main/backend/note_index.py): `backend/note_index.py`
- [Search and navigation](https://github.com/gamosoft/notediscovery/blob/main/backend/utils.py): `backend/utils.py`
- [Links and graph](https://github.com/gamosoft/notediscovery/blob/main/backend/note_index.py): `backend/note_index.py`

### Extensions

- [Plugin system](https://github.com/gamosoft/notediscovery/blob/main/backend/plugins.py): `backend/plugins.py`
- [Plugin extensions](https://github.com/gamosoft/notediscovery/tree/main/plugins): `plugins`

### AI integration

- [MCP server](https://github.com/gamosoft/notediscovery/blob/main/mcp_server/server.py): `mcp_server/server.py`
- [MCP tools](https://github.com/gamosoft/notediscovery/blob/main/mcp_server/tools.py): `mcp_server/tools.py`
- [HTTP API client](https://github.com/gamosoft/notediscovery/blob/main/mcp_server/client.py): `mcp_server/client.py`
- [MCP configuration](https://github.com/gamosoft/notediscovery/blob/main/mcp_server/config.py): `mcp_server/config.py`

### Other components

- **User**
- **AI assistant**

## Connections

- User → Web app: uses (evidence: `README.md`)
- Web app → FastAPI application: requests data
- FastAPI application → Markdown storage: reads notes (evidence: `backend/main.py`)
- FastAPI application → File and Markdown utilities: calls (evidence: `backend/main.py`)
- File and Markdown utilities → Note index: uses extraction (evidence: `backend/utils.py`)
- FastAPI application → Plugin system: dispatches hooks (evidence: `backend/main.py`)
- FastAPI application → Search and navigation: serves discovery (evidence: `backend/main.py`)
- FastAPI application → Links and graph: serves graph (evidence: `backend/main.py`)
- FastAPI application → Public sharing: handles sharing (evidence: `backend/main.py`)
- FastAPI application → HTML export: handles export (evidence: `backend/main.py`)
- FastAPI application → Theme management: serves themes (evidence: `backend/main.py`)
- Plugin system → Plugin extensions: loads extensions
- AI assistant → MCP server: requests note actions (evidence: `README.md`)
- MCP server → HTTP API client: calls (evidence: `mcp_server/server.py`)
- MCP server → MCP tools: uses definitions (evidence: `mcp_server/server.py`)
- MCP server → MCP configuration: loads settings (evidence: `mcp_server/server.py`)
- HTTP API client → FastAPI application: sends HTTP requests (evidence: `mcp_server/client.py`)
