DEV Community: codexu

How NoteGen handles sync queues and conflicts in a local-first Markdown app

codexu — Fri, 31 Jul 2026 13:21:41 +0000

codexu/note-gen is an open-source, local-first Markdown note-taking app. Notes live as regular files in the user's workspace. GitHub, Gitee, GitLab, Gitea, S3, and WebDAV are optional sync targets rather than the primary store.

That ownership model creates a less obvious engineering problem. An editor save, a filesystem write, and a remote upload do not happen at the same time. Save events may fire repeatedly while someone is typing, and another device may change the same file before the next upload starts.

A direct save -> upload path would be easy to build, but it would also generate noisy requests and make stale writes more likely. NoteGen splits the job into three parts: an in-memory push queue, remote-version checks, and explicit conflict handling.

Save events enqueue paths, not content

The main entry point is src/lib/sync/sync-push-queue.ts. A singleton SyncPushQueue is initialized from src/app/layout.tsx and listens for four events:

article-saved adds the file path to the queue;
editor-input refreshes the last-input timestamp;
sync-pulled prevents a fresh pull from immediately bouncing back as a push;
article-opened resets the idle calculation when the active file changes.

The queue reads the user's auto-sync interval and checks for idleness every 100 milliseconds. It only calls flush() after the configured quiet period has passed.

The delay is not only a request-saving debounce. Before each upload, the queue waits another 100 milliseconds for the filesystem write to settle and then reads the file from disk again. The event answers “which path changed?”; the workspace answers “what is the latest content?”

That distinction matters in a local-first editor. React state and editor events are transient. The Markdown file on disk is the durable fact the user owns.

It deduplicates by path, but it is not a durable job queue

During flush(), pending tasks are grouped in a Map keyed by path. Repeated saves for one file collapse into the newest task. Different paths are processed from newest to oldest. If another save happens while an upload is running, the new task is appended and scheduled after the current batch.

This is intentionally smaller than a general-purpose message queue. It lives in memory and does not recover pending work after an application restart. Before processing begins, a new addTask() call also replaces the current queue with the latest task. The design optimizes for the final state of an interactive editing session, not delivery of every intermediate snapshot.

An application that must deliver every file mutation would need persisted jobs, task states, restart recovery, and probably idempotency keys. A notes editor usually cares more about the final file than the version produced after each keystroke, so NoteGen accepts the narrower guarantee.

Read remote content before writing it

When a push begins, the queue first calls pullRemoteFile(). If the remote content is byte-for-byte equal to the local file, it skips the upload and only refreshes the locally recorded remote SHA. This avoids creating another commit when a save event fires without a content change.

For GitHub, Gitee, GitLab, and Gitea, the queue then fetches the current remote file metadata again and passes its SHA to the provider's upload function. That SHA acts as an optimistic concurrency token: update the file only if the remote version still matches the version we just observed.

After a successful upload, the returned remote SHA is stored in Tauri Store under syncedFileShas. On a later open or sync, compareFileVersions() in src/lib/sync/auto-sync.ts compares the recorded SHA with the current remote SHA. A mismatch means the remote file changed since this device last synchronized it.

The local content hash and the remote identifier are not interchangeable. Local content uses SHA-256, while Git providers may expose blob or commit identifiers. NoteGen therefore treats the remote SHA as a remote-version cursor, then uses local modification time, remote commit time, and the last sync time for additional decisions.

There is also a ten-second grace period after a pull or restore. If writing remote content makes the local file appear newer for a moment, the grace period stops that filesystem timestamp from triggering an immediate push back to the server.

A conflict is not a transient network error

The push queue classifies HTTP 409 and 422 responses, along with messages containing terms such as sha, blob, out of date, or conflict, as version mismatches.

On the first mismatch, it does not keep retrying the same stale write. It emits a sync-sha-mismatch event containing the path and the known local and remote identifiers. src/components/sync-confirm-dialog.tsx consumes that event and asks the user whether to keep the local version. Only an explicit confirmation enters the forcePush() path; cancelling leaves the remote file unchanged.

Pulls have a separate content-level conflict path in src/lib/sync/conflict-resolution.ts:

identical content needs no action;
a pure tail addition can be merged;
content that only differs in whitespace can be treated as a formatting change;
larger differences require a local-or-remote decision.

The merge is deliberately conservative. It is not a Markdown AST merge or a three-way merge, and it cannot understand two edits to the same paragraph. Asking the user is safer than manufacturing a document that looks valid while silently dropping meaning.

One workflow does not mean one consistency model

All six providers pass through the same queue, but they do not provide identical conflict guarantees.

Git-based providers expose SHAs or commit identifiers that fit optimistic concurrency checks. S3 and WebDAV store ETags in local sync state, but their current upload paths are primarily direct writes; they are not yet normalized into conditional requests with the same semantics as a Git SHA update.

Provider adapters also differ in how they return or throw errors. The queue can only recognize a structured 409 or 422 if the adapter preserves that information. A shared upload() shape is the easy part of multi-provider sync. The hard parts are version tokens, conditional writes, error classification, and a recovery action the user can understand.

NoteGen currently shares scheduling and confirmation flows across providers while keeping those backend differences visible in the implementation.

Four rules worth carrying into another local-first app

The implementation suggests four practical rules:

Enqueue a path, then read the latest file from disk immediately before upload.
Combine idle detection with per-path deduplication for high-frequency editor saves.
Persist the remote version identifier as the baseline for the next sync.
Treat network failure and version conflict as different states; the latter may require a user decision.

The useful measure of a sync system is not whether every request succeeds. It is whether latency, multi-device edits, and different storage protocols can be handled without making an irreversible overwrite on the user's behalf.

The original Chinese version is available on Juejin.

NoteGen is a cross-platform Markdown note-taking application

codexu — Thu, 29 May 2025 06:33:12 +0000

Why Choose NoteGen?
Lightweight: Installation package is only 20MB, free with no ads or bundled software.
Cross-platform: Supports Mac, Windows, Linux, and thanks to Tauri2's cross-platform capabilities, will support iOS and Android in the future.
Supports multiple recording methods including screenshots, text, illustrations, files, links, etc., meeting fragmented recording needs across various scenarios.
Native Markdown(.md) as storage format, no modifications, easy to migrate.
Native offline usage, supporting real-time synchronization to GitHub, Gitee private repositories with history rollback, and WebDAV synchronization.
AI-enhanced: Configurable with ChatGPT, Gemini, Ollama, LM Studio, Grok, and other models, with support for custom third-party model configuration.
Github: https://github.com/codexu/note-gen

💻 AI-Powered NoteGen: Transform Your Fragments into Masterpieces!

codexu — Wed, 30 Apr 2025 05:55:31 +0000

💻 Hey everyone, if you're tired of messy notes and want a simple way to turn your ideas into polished pieces, let me introduce you to NoteGen! 😍 It's this amazing AI-driven app that bridges recording and writing effortlessly. 🚀 As a busy note-taker myself, I've found it super helpful for organizing thoughts without the hassle.
📝 First off, why pick NoteGen over others? 🌟 It's lightweight at just a few megabytes, completely free, and ad-free – no sneaky bundles here! 😊 It works on Mac, Windows, Linux, and even plans for iOS and Android soon, thanks to its cross-platform tech. 💪 Plus, it handles all sorts of inputs like screenshots, text, images, files, and links, making every scenario a breeze.
🚀 Diving deeper, NoteGen splits into two awesome parts: recording and writing. 😎 In recording mode, it's like chatting with an AI bot that ties in your existing notes, and you can switch to organize mode to tidy up fragments into readable docs. 🌈 Features like tags for sorting, custom prompts for your AI helper, and a clipboard assistant that auto-grabs text or pics make it a game-changer. 📌 Don't forget the writing side, with a file manager for easy Markdown handling and an editor that offers real-time previews, AI for polishing text, and even tools for charts or formulas.
🔄 What I love most is how it supports offline use, syncs to GitHub, and has AI from models like ChatGPT or Gemini. 😊 It's perfect for deep writing sessions where you can insert records on the fly and roll back changes if needed. 🌟 If you're into customization, tweak themes, search globally, or manage your image uploads easily. Trust me, it's a total efficiency boost!
💡 So, what's your go-to note app right now? 😏 Give NoteGen a try and share your thoughts in the comments – I'd love to hear how it works for you! Remember, it's in alpha but already packs a punch. Let's level up our note-taking game together! ✨

https://github.com/codexu/note-gen

NoteGen Markdown Editor

codexu — Thu, 17 Apr 2025 06:01:59 +0000

Github: https://github.com/codexu/note-gen

NoteGen is a cross-platform Markdown note-taking application dedicated to using AI to bridge recording and writing, organizing fragmented knowledge into a readable note.

Why Choose NoteGen?

Lightweight: Installation package is only about 10MB, free with no ads or bundled software.
Cross-platform: Supports Mac, Windows, Linux, and thanks to Tauri2's cross-platform capabilities, will support iOS and Android in the future.
Supports multiple recording methods including screenshots, text, illustrations, files, links, etc., meeting fragmented recording needs across various scenarios.
Native offline usage with Markdown(.md) as the storage format, while also supporting real-time synchronization to private GitHub repositories with history rollback.
AI-enhanced: Configurable with ChatGPT, Gemini, Ollama, LM Studio, DeepSeek, and other models, with support for custom third-party model configuration.

Screenshots

Recording:

Writing:

Dark Mode:

From Recording to Writing

Conventional note-taking applications typically don't provide recording functionality. Users need to manually copy and paste content for recording, which greatly reduces efficiency. When faced with scattered recorded content, it requires significant effort to organize.

NoteGen is divided into Recording and Writing pages, with the following relationship:

Recordings can be organized into notes and transferred to the writing page for in-depth composition.
During writing, you can insert recordings at any time.

Recording

The recording function is similar to an AI chatbot, but when conversing with it, you can associate it with previously recorded content, switching from conversation mode to organization mode to arrange recordings into a readable note.

The following auxiliary features can help you record more effectively:

Tags to distinguish different recording scenarios.
Personas with support for custom prompts to precisely control your AI assistant.
Clipboard Assistant that automatically recognizes text or images in your clipboard and records them to your list.

Writing

The writing section is divided into two parts: File Manager and Markdown Editor.

File Manager

Supports management of local Markdown files and GitHub synchronized files.
Supports unlimited directory hierarchy.
Supports multiple sorting methods.

Markdown Editor

Supports WYSIWYG, instant rendering, and split-screen preview modes.
Supports version control with history rollback.
Supports AI assistance for conversation, continuation, polishing, and translation functions.
Supports image hosting, uploading images and converting them to Markdown image links.
Supports HTML to Markdown conversion, automatically converting copied browser content to Markdown format.
Supports outlines, math formulas, mind maps, charts, flowcharts, Gantt charts, sequence diagrams, staves, multimedia, voice reading, title anchors, code highlighting and copying, graphviz rendering, and plantuml UML diagrams.
Supports real-time local content saving, delayed (10s without editing) automatic synchronization, and history rollback.

Other Features

Global search for quickly finding and jumping to specific content.
Image hosting management for convenient management of image repository content.
Themes and appearance with support for dark themes and appearance settings for Markdown, code, etc.
Internationalization support, currently available in Chinese and English.

How to Use?

Download

Currently supports Mac, Windows, and Linux. Thanks to Tauri2's cross-platform capabilities, it will support iOS and Android in the future.

Download NoteGen (alpha)

Enhancement

The note-taking application can be used directly without configuration. If you want a better experience, please open the settings page to configure AI and synchronization.

Community

Welcome to join the NoteGen community group where you can ask questions, share usage experiences, or suggest improvements. You can also join to learn about Tauri and discuss it with me.

Scan the QR code to join the discussion group. If the QR code expires, you can add WeChat xu461229187 to join the group.

Contribute

NoteGen is implemented using the following technology stack:

How to contribute:

NoteGen is a cross-platform AI note-taking application focused on recording and writing, developed based on Tauri.

codexu — Mon, 03 Mar 2025 06:06:20 +0000

The core philosophy of NoteGen is to combine recording, writing, and AI, with all three complementing each other. The recording function helps users quickly capture and organize fragmented knowledge. The organization function is the bridge connecting recording and writing, which can organize continuously recorded content into a readable note, assisting users in completing the creation process from scratch. If the AI-organized results cannot meet your requirements, you can use the writing function to refine it yourself.

Github

Recording
Recording methods supported:

🖥️ Screenshot recording, through which users can quickly capture and record fragmented knowledge, especially in situations where text copying is not possible.
📄 Text recording, which allows copying text or manually inputting brief content as a record.
🖼️ Illustration recording, which can be automatically inserted into appropriate positions when generating notes.
📇 File recording, which recognizes content from PDF, md, html, txt, and other files for text recording.
🔗 Link recording (to be implemented), using web crawlers for page content recognition and recording.
📷 Photo recording (to be implemented), similar to illustration recording, calling the camera to record, suitable for future mobile use.
Auxiliary recording:

🏷️ Custom tags for better categorization and differentiation of different recording scenarios.
🤖 AI conversation, by default associated with records under the current tag, and you can also manually associate it with any article in your writing.
📋 Clipboard recognition, which automatically recognizes images or text in the clipboard after you copy them.
💾 Organization, when you have completed a series of records, you can try to let AI help you organize them into an article.
Writing
🗂 File manager, supporting management of files and folders in local and Github repositories, with unlimited directory levels.
📝 Support for WYSIWYG, instant rendering, and split-screen preview modes.
📅 Version control, if you enable synchronization, you can trace back to historically uploaded records in the history.
🤖 AI assistance, supporting Q&A, continuation, optimization, simplification, translation, and other functions, and you can insert records into any position of the article at any time.
🏞️ Image hosting, directly copy and paste images into the Markdown editor, which will automatically upload the image to the image hosting service and convert it to a Markdown image link.
🛠️ HTML and Markdown conversion, copying content from browsers will automatically convert it to Markdown format.
Auxiliary
📦 Large model support, with multiple built-in large model configurations, supporting customization and easy switching.
👁️ OCR, which can assist in recognizing text in images.
🏗️ Organization templates, which can be customized for AI to organize different types of content.
🔎 Global search, for quickly searching and jumping to specified content.
🌃 Image hosting management, for convenient management of image hosting repository content.
💎 Themes and appearance, supporting dark theme, and appearance settings for Markdown, code, etc.
How to Use?
Download
Currently supports Mac, Windows, Linux, and thanks to Tauri2's cross-platform capabilities, it will support iOS and Android in the future.

Download NoteGen (alpha)

Getting Started Guide
If you are not familiar with NoteGen, you can read the user documentation, which includes a quick start guide:

NoteGen User Documentation

AI Model Integration
Currently supports custom model configuration, with built-in support for ChatGPT, ChatAnyWhere, Ollama, LM Studio, Doubao, Tongyi Qianwen, Kimi, DeepSeek, and all models using the OpenAI protocol. Support for other protocols will be gradually added in the future.

Local models may currently experience 403 errors, waiting for a solution from http-plugin. This issue does not occur in the development environment.

Discussion Topic - About Model Integration

Synchronization and Image Hosting
NoteGen supports offline storage, with all notes stored in Markdown format. To ensure the security of your notes, you can choose to synchronize them to a private Github repository. After configuring synchronization, Github image hosting functionality is also supported. Independent configuration for other image hosting services will be supported in the future.

Contribute
NoteGen is implemented using the following technology stack:

Tauri 2
Next.js 15
shadcn-ui
Participate in contributions:

Update Plan
Submit Bug or Improvement Suggestions
Discussions
If you are learning Tauri, you can follow my series 《Tauri Open Source Diary》.