Notely

Notely Application Architecture ​

Notely is an offline-first, local-first markdown note-taking and knowledge management application built using Electron, React, CodeMirror 6, and Node.js.

1. High-Level Architecture Overview ​

Notely separates execution between a sandboxed Renderer Process (React UI) and a privileged Main Process (Node.js backend) communicating via secure IPC channels.

2. Renderer Layer (React & Editor Architecture) ​

The user interface is powered by React 18, Vite, and custom CSS variables supporting dynamic light/dark mode themes.

Component Structure ​

  • App Shell (App.jsx): Manages primary navigation, view routing, full-screen page overlays (KnowledgeGraph, EmbeddingsPage, AppLogsPage, AIPersonasManager, AIHealthPage, GitVC), and footer status bar.
  • Layout Engine (LandingView.jsx, EditorPane.jsx, DocumentDetail.jsx): Responsive split-pane layout supporting Edit mode, Preview mode, and Live Split View.
  • Editor Core (CodeMirrorEditor.jsx, MarkdownEditor.jsx): Built on CodeMirror 6 with custom extensions for syntax highlighting, line numbers, block folding, spell-checking, search/replace, and hotkeys.
  • Preview Renderer (MarkdownPreview.jsx): Full GitHub-Flavored Markdown (GFM) renderer supporting LaTeX equations (katex), task lists, local media resolution, and Wikilink navigation ([[Note]]).
  • Mermaid.js Integration: Real-time evaluation and SVG rendering of GFM code blocks (```mermaid) for flowcharts, sequence diagrams, class diagrams, Gantt charts, and mindmaps across preview mode, split view, and exported documents.
  • Excalidraw Drawing Editor: Embedded interactive whiteboard component allowing users to sketch visual diagrams, hand-drawn wireframes, and architectural schematics. Drawings are persisted as human-readable .excalidraw JSON files or embedded SVG graphics inside workspace notes.

State Management & Contexts ​

  • UIStateContext.jsx: Controls global dialogs, sidebar panels, active full-screen pages, theme preferences, and zoom factors.
  • DocumentContext.jsx: Tracks the open document list, active document handle, unsaved dirty states, file content buffers, and document metadata.

3. Main Process & Application Subsystems ​

The Electron main process (electron/main.cjs & electron/lib/) coordinates application logic across core subsystems:

A. Document & File System Service ​

  • File Watcher (chokidar): Watches workspace directory tree recursively for external file additions, edits, renames, and deletions.
  • Subfolder & Path Traversal: Resolves relative note paths, handles file CRUD operations safely, and computes workspace-wide document statistics.

B. Git Version Control Subsystem (gitService.cjs) ​

  • Local Git Execution: Runs native git CLI commands synchronously or asynchronously without external cloud dependencies.
  • Feature Set: Workspace initialization, status tracking (staged/unstaged files), diff generation, commit creation, branch management, remote push/pull synchronization, and commit history inspection.

C. Package, Import & Export Subsystem (notePackageIpc.cjs) ​

Document Exporters:

  • Exports individual markdown notes to HTML and PDF formats via Headless Chromium rendering (CSS theme applied, media resolved).

Note Package System (.note bundle format):

  • Bundles selected .md files with all linked assets into a single portable .note file via File → Export / Import Note Package.
  • Bundled assets: markdown files, media/images/, Excalidraw diagrams (.notes-app/excali-diagrams/), Draw.io diagrams (media/draw.io/), and auto-generated metadata.json.
  • Security: AES-256 encrypted bundle (not readable by generic ZIP tools). Each file is SHA-256 hashed and verified on import to reject tampered packages. Optional password protection stores a salted SHA-256 signature in the manifest.
  • Import: Decrypts and verifies bundle integrity, resolves asset path conflicts, and places all files into the active workspace. See Export & Import Reference for full user-facing documentation.

D. Multi-Format Document Extraction Subsystem (DocumentExtractionService.cjs) ​

  • Multi-Format Parsing Engine: Extract and convert complex binary documents into clean, structured Markdown:
    • Word documents (.docx) using OpenXML text & table parser (DocxExtractor.cjs).
    • Spreadsheets (.xlsx, .xls, .csv, .tsv) using SheetJS workbook extraction (SpreadsheetExtractor.cjs).
    • Presentations (.pptx) with slide hierarchy and presenter notes (PptxExtractor.cjs).
    • PDF documents (.pdf) with spatial line clustering (PdfExtractor.cjs).
  • Document Cache Store (DocumentCacheStore.cjs): SQLite-backed document store (.notes-app/documents.db) and disk cache (.notes-app/extracted/) storing content hashes, page counts, word counts, and extracted markdown chunks for instantaneous retrieval.

E. Model Context Protocol (MCP) Subsystem (McpServer.cjs) ​

  • Streamable HTTP & SSE Server: Embedded dual-transport MCP server listening by default on port 3700 exposing workspace capabilities to external AI clients (Google Antigravity, Claude Desktop, Cursor, IDE agents).
  • Enterprise Capabilities: Registers 7 unified enterprise tools (search, read_note, edit_note, manage_tasks, manage_diagrams, workspace_overview, git_control) and 9 standard MCP prompts (summarize_note, plan_tasks, explore_knowledge_graph, refactor_note, daily_review, synthesize_document, create_diagram, atomic_split, codebase_sync). See Enterprise MCP Tools & Prompts Reference.
  • Permission Control: Enforces allowWriteTools configuration toggle; rejects unauthorized write operations ([W]) automatically.
  • Telemetry Flight Log: Records tool execution events in SQLite database and streams updates via IPC to AIHealthPage.jsx.

F. External AI IDE Bridge & Workspace Ignore Engine (AiContextBridgeService.cjs) ​

  • Context Bridge: Background worker that automatically synchronizes real-time workspace sitemaps, open tasks, knowledge hubs, and extracted binary documents into .notes-app/ai/dynamic-context.md, AGENTS.md, CLAUDE.md, .cursorrules, and .vscode/prompts/.
  • Workspace Ignore Policy (workspaceIgnorePolicy.cjs): Single Source of Truth for ignoring build, dependency, and private system directories across File Tree, Knowledge Graph, Semantic Embeddings, Document Extractions, Task DB, MCP Tools, and external AI bridges. Supports .notelyignore and .gitignore.

G. Knowledge Graph & Vector Embedding Subsystem ​

  • Vector Embeddings Engine (EmbeddingDB.js): Stores 384-dimensional BGE-small vector chunks in {workspace}/.notes-app/ai-embeddings.db. Features physical vector dimension validation (verifyModelDimensions) to prevent dimension mismatches.
  • Knowledge Graph Subsystem (GraphService.js, GraphDB.js): Maps note relations, tags, mentions, Wikilinks, Images, Local Documents, and External URLs in {workspace}/.notes-app/ai-graph.db. Executes relation traversals via SQLite Recursive Common Table Expressions (CTEs).
  • Local ONNX Embedder: Vector embeddings (BGE-small-en-v1.5) and Knowledge Graph entity/relationship extraction run on-device and offline using onnxruntime-node.

AI Layer Architecture ​

The following diagram shows the full request path from the React UI through each layer to inference and storage:

F. Model Context Protocol (MCP) Server Subsystem (electron/mcp/) ​

  • Streamable HTTP & SSE Server (McpServer.cjs): Embedded MCP server (default port 3700) exposing Notely workspace capabilities over Streamable HTTP (/mcp, /sse, /) and legacy SSE (/sse, /messages) with Bearer token authentication and session ID tracking.
  • Lifecycle Controller (McpLifecycle.cjs): Manages MCP server lifecycle, port settings (mcp-config.json), IPC status broadcasting (mcp:status-changed), and graceful app shutdown.
  • Session Manager (McpSessionManager.cjs): Tracks active client connections, remote User-Agents, request durations, and tool invocation stats.
  • Application Tool Registry (ApplicationToolRegistry.cjs): Exposes 7 self-sufficient enterprise tools for note operations, workspace multi-modal search, knowledge graph queries, task management, diagram management, git operations, and workspace metadata.
  • Capabilities & Diagnostics UI: Integrated React views MCPToolsPage.jsx (Interactive capabilities catalog & terminal test runner) and AIHealthPage.jsx (MCP server telemetry & Streamable HTTP / SSE session diagnostics). See Developer MCP Guide for detailed API schemas.

For a detailed walkthrough of each layer, see AI Subsystem Architecture.

4. Centralized System Logging Infrastructure (LogDB.js) ​

Logging across Notely is managed by a centralized, generic SQLite log store (LogDB.js).

Database Schema ​

Logs are persisted inside the active workspace directory at {workspace}/.notes-app/ai-logs.db:

sql
CREATE TABLE IF NOT EXISTS logs (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  subsystem TEXT NOT NULL,
  level TEXT DEFAULT 'info',
  message TEXT NOT NULL,
  metadata TEXT,
  timestamp TEXT NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_logs_subsystem ON logs(subsystem);

Log Subsystem Categories ​

  • app: Application startup, settings updates, file system I/O, package import/export.
  • git: Git status checks, staging, commits, diffs, branch operations.
  • embeddings: Vector indexing pipeline, model loading, chunking, database updates.
  • graph: Knowledge Graph entity extractions, relationship linking, graph rebuilds.
  • ai: LLM queries, tool invocations, prompt context assembly.

User Diagnostics & Management UI ​

  • System Logs Console (AppLogsPage.jsx): Accessible via Help -> System & Application Logs. Features live search, subsystem/severity dropdown filters, live auto-refresh toggle, log clearing, and JSON log export.
  • Subsystem Log Feeds: Embedded log panels inside EmbeddingsPage and KnowledgeGraph display real-time subsystem-filtered events.
  • Subsystem Data Clear Buttons: EmbeddingsPage features a Clear Embeddings Data button (aiClearEmbeddingsData), and KnowledgeGraph features a Clear Knowledge Graph Data button (aiClearGraphData) to clear data caches independently of logs.

5. Data Storage & Workspace Directory Structure ​

Notely maintains a clean separation between global application config, human-readable workspace files, and local metadata caches:

Workspace Storage Diagram ​

Global Configuration ​

  • Global App Database (%APPDATA%/Notely/app.sqlite): Manages user preferences, API keys, active themes, window dimensions, and recently opened workspaces.

Workspace File Structure ​

  • Raw .md Files: Notes are saved as plain-text UTF-8 Markdown files directly in workspace root and subdirectories ({workspace}/**/*.md). Notely imposes zero proprietary database wrapping or lock-in, enabling seamless external editing with Git, VS Code, or Obsidian.
  • Media/ Assets Folder: A dedicated assets directory located at {workspace}/Media/ created to house user-attached media files:
    • Images (.png, .jpg, .jpeg, .gif, .svg, .webp).
    • Video & Audio recordings (.mp4, .webm, .mp3, .wav, .m4a).
    • Document attachments (.pdf).
    • Excalidraw drawing files (.excalidraw).
  • Hidden Subsystem Folder ({workspace}/.notes-app/): Internal SQLite caches for AI, tasks, documents, and system features:
    • documents.db: Stores document extraction records, content hashes, extraction status, and parsed metadata.
    • extracted/: Stores cached raw Markdown representations of office and PDF documents.
    • task-db.sqlite: Stores workspace-wide task metadata, priorities, due dates, assignee tags, source note hashes, and line indices for bi-directional checklist synchronization.
    • ai-embeddings.db: Stores chunk text, line offsets, hashes, and 384-dimensional binary vector BLOBs.
    • ai-graph.db: Stores extracted Knowledge Graph entity nodes, Wikilinks, media links, and relationship edges.
    • ai-logs.db: Stores multitenant application, git, embedding, graph, and AI log entries.
    • wireframes/: Stores GrapesJS UI prototype project JSON definitions (.wireframe.json).
    • app-state.json: Caches workspace UI state, last opened note handles, and view preferences.