FleshNote
FLESHNOTE π³Œπ³–π³‰π³€π³™π³›π³¦π³‰
DOCS // v1.3.0
Patchnotes GitHub
FLESHNOTE / DOCS / INTRODUCTION

FleshNote Developer Documentation

v1.3.0 BETA

A comprehensive technical manual and architectural reference for the FleshNote novel-writing IDE, its 3-layer IPC pipeline, linguistic intelligence engines, epistemic state machine, and serverless sync protocol.

Updated: August 2026
License: MPL 2.0 (FOSS)
Stack: Electron + React + FastAPI
Developer-First Architecture FleshNote is built on a strict local-first philosophy. All prose, SQLite databases, and linguistic models reside completely on the user's physical machine. There are no mandatory cloud subscriptions, no external tracking telemetry, and no lock-in.

Overview & Philosophy #

FleshNote is envisioned strictly as a writing-oriented IDE devoid of the conventional distractions found in overbearing world-building toolsets. It prioritizes placing words onto the page via a clean minimal IDE editor while shifting the heavier, lore-centric overhead into secondary, optionally accessible UI panels and background NLP extraction.

  • Writing First: An unencumbered Markdown canvas designed around pure narrative drafting, target word goals, and focus sprint modes.
  • Abstract Tracking: Background linguistic and NLP engines (spaCy, NLTK) natively audit sensory density and extract characters, locations, and lore without manual data entry.
  • Seamless Epistemic UI: Features structured around "who knows what". Knowledge states, secrets, and foreshadowing markers are injected without corrupting the prose.

3-Layer IPC System Architecture #

Every user interaction that reads or modifies persistent project data follows a secure 3-layer Inter-Process Communication (IPC) boundary. React components never make direct system calls or query the database directly.

FleshNote 3-Layer Inter-Process Communication Stack
1. React Renderer (Frontend) src/renderer/src/components (Editor, Inspector, Popups)
window.api.method()
β–Ό contextBridge (Secure IPC Isolation)
2. Preload & Electron Main Process src/preload/index.ts & src/main/index.ts (backendPost helper)
ipcRenderer.invoke()
β–Ό HTTP POST over Loopback (http://localhost:8000)
3. Python FastAPI Daemon & Storage backend/main.py, backend/routes/*, SQLite (WAL) + Markdown files
FastAPI + SQLite

Documentation Directory #

Explore the documentation across 8 technical domains. Each guide includes code snippets, database schemas, and architectural patterns:

1. Architecture & IPC
Detailed IPC data flows, Preload contextBridge, FastAPI daemon management, and directory layout.
Tech Stack 3-Layer IPC Dev Setup
2. Editor & Inline Syntax
TipTap ProseMirror engine, tag serialization matrix, nested bracket avoidance quirk, sprint flow, and #TODO engine.
Tag Matrix Time Gutter #TODO \u200B
3. Entity System & Graph
Unified Entity Manager, time-based knowledge states, relationship dynamics, 5-level weather inheritance, and plot twists.
Knowledge POV Relationships Weather Tree
4. NLP & The Janitor
The 9-analyzer Janitor auditor, Show Don't Tell scoring, multilingual language support matrix, and procedural name phonology.
9 Analyzers Language Matrix Phonology
5. Pentimento Telemetry
Writing process telemetry, edit coalescing, SHA-256 session sealing, paragraph heatmap, and replay simulation.
Op Coalescing Effort Heatmap Replay Engine
6. Storage & Sync
SQLite WAL schema, v1 to v2 UUID migration, Hybrid Logical Clock (HLC), change logging, and multi-device merge.
SQLite Schema HLC Sync 3-Way Merge
7. Export & Builds
Manuscript Standard DOCX, Print-Ready PDF with running headers, EPUB compilation, and PyInstaller bundling.
DOCX / PDF / EPUB PyInstaller Flatpak
8. API & Cookbook
FastAPI route registry, Electron preload IPC catalog, and practical tutorials for extending FleshNote features.
FastAPI Endpoints window.api Catalog Dev Recipes
9. App Brand & Design
Name origin (FleshStone), Hungarian RovΓ‘s ΓΆsszerovΓ‘s logo ligature, hard edges rule, entity color semantics, and opinionated UI.
RovΓ‘s Runes Hard Edges Opinionated UI
10. Doc Style Standards
Standards for alert panels (notes, warnings, tips), typography hierarchy, code syntax, and UI consistency rules.
Alert Panels Typography Code Format
11. Contributor Guide
Contribution priorities: localization, language NLP refining, Markov name tables, place generator rules, and anti-bloat policy.
Priorities NLP Refining Anti-Bloat

Developer Quickstart #

To run FleshNote IDE locally in development mode:

Bash / Terminal 
# 1. Clone the repository and navigate into the IDE directory
git clone https://github.com/ArtFacility/FleshNote.git
cd FleshNote/fleshnote-ide

# 2. Install Node frontend dependencies
npm install

# 3. Setup the Python 3.13 backend virtual environment
cd backend
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
cd ..

# 4. Launch the application in hot-reload development mode
npm run dev

Core Architectural Principles #

Principle Implementation Mechanism Architectural Benefit
Zero Cloud Lock-in Local SQLite in WAL mode at {project}/fleshnote.db + plain Markdown chapter files. Authors have 100% data ownership; files remain readable outside FleshNote forever.
Slim Distribution Dynamic AppData downloader for spaCy NLP models and NLTK word nets. Installer binary remains tiny (<100MB) without bundling multi-gigabyte neural models.
Epistemic Integrity Dynamic SQL queries evaluating POV context against fact visibility tables. Prevents narrative plotholes by tracking character knowledge independently of author knowledge.
Collision-Free Sync UUID primary keys, column-level change_log, and Hybrid Logical Clock (HLC). Enables serverless, peer-to-peer merge across desktop and companion devices without integer ID collisions.
On This Page