DEV Community

Joe Greenwood
Joe Greenwood

Posted on

Local first Markdown Workspace - FastAPI + PySide + distributed sync

#fastapi #productivity #python #showdev

Building StillPoint: A Local-First Markdown Workspace with a Server Core

Most note-taking tools fall into one of two camps:

  • Pure desktop apps that never think about networking (or paid models to get there...)
  • Cloud-first systems that treat your data as something hosted somewhere else

I wanted something different.

I built StillPoint as a local-first Markdown workspace that treats the file system as the source of truth — but is architected around a server model from day one.

This post walks through why I built it, how it’s structured, and what tradeoffs I’ve made.

The Problem I Was Trying to Solve

Over time I found myself juggling:

  • Notes in one tool
  • Tasks in another
  • Journal entries somewhere else
  • Diagrams in yet another place

And many of them were:

  • Cloud-dependent
  • Locked behind accounts
  • Or heavy with abstractions

I wanted:

  • Notes + tasks + planning in one surface
  • Markdown files on disk
  • Something calm
  • Something I could reason about
  • Something I could run entirely locally

But I also didn’t want to paint myself into a “single-device desktop app” corner.

Core Philosophy

StillPoint is built around a few principles:

  • Local-first by default
  • Markdown-first (human-readable, tool-agnostic)
  • Folder-per-page structure (filesystem-native)
  • No proprietary lock-in
  • AI optional and opt-in
  • Progressive complexity (simple solo use first, remote/sync later)

If the app disappears tomorrow, your vault is still a folder of Markdown files.

Architecture: Desktop + Server, Even Locally

Even in “local mode”, StillPoint runs a server.

Here’s the simplified model:

Desktop UI → HTTP → StillPoint Server → Filesystem Vault

The server is built with FastAPI and:

  • Reads/writes Markdown files directly
  • Manages search (SQLite FTS)
  • Handles tasks parsing
  • Exposes endpoints for links, journal, attachments, etc.

Why use a server internally?

Because that unlocks:

  • A web UI
  • A PWA for quick task updates
  • Remote access
  • A distributed sync engine

All without changing the core vault model.

Notes, Tasks, and Planning in One Surface

Instead of splitting “notes” and “tasks” into different systems:

Tasks are written directly inside notes:

  • [ ] Review proposal
  • [ ] Ship release @high

The system parses:

  • Checkboxes
  • Dates
  • Priorities
  • Tags

There’s a task panel, calendar view, and journal layout:

Journal/YYYY/MM/DD/DD.md

Graph navigation lets you explore relationships, and “project mode” lets you filter from a specific root page — effectively zooming into a contextual slice of the vault.

This has been especially useful for client or project-based work.

Focus and Audience Modes

One thing I wanted was control over noise.

StillPoint includes:

  • Focus Mode (distraction-free writing)
  • Audience Mode (simplified UI for screen sharing)
  • Optional vi-style navigation for keyboard-heavy workflows

It’s designed to feel quiet, not busy.

AI (Optional, Not Required)

AI is supported but not mandatory.

You can:

  • Run against local model servers
  • Use OpenAI-compatible APIs
  • Configure your own endpoints

Features include:

  • Page-scoped chat
  • Global chat
  • Draft/refine/transform actions
  • Agent/tool loops

But if you never enable AI, the app still works completely fine.

Remote Models and Sync

There are two remote approaches.

Remote Vault (Server-Trusted)

  • Server stores plaintext Markdown
  • JWT-based authentication
  • Role-based permissions

Suitable for trusted/self-hosted setups.

Homebase (Distributed / Zero-Trust Model)

  • Encrypted object replication
  • Server stores opaque blobs
  • Client-side key derivation
  • Push/pull checkpoint sync
  • Offline-first with conflict handling

The idea is to separate:

  • Authentication
  • Storage
  • Confidentiality

I’m still refining this model and welcome feedback.

Tradeoffs

StillPoint is not:

  • A SaaS product
  • A real-time collaborative editor
  • A CRDT-based multi-user system

It favors:

  • Simplicity
  • File transparency
  • Explicit structure
  • User-controlled sync

Stack

  • Python
  • PySide6 (desktop UI)
  • FastAPI (server)
  • SQLite FTS
  • JSON config
  • Markdown vault on disk

Why Build This?

Because I wanted:

  • A calm place to think
  • A journal that lives beside project work
  • A task system inside notes
  • A graph that can be filtered by context
  • A server model without losing local-first principles

StillPoint is open source and runnable locally. No signup required.

GitHub: https://github.com/grnwood/stillpoint
Site: https://stillpoint.info/

If you’re interested in local-first software, distributed sync models, or file-based workflows, I’d love feedback.

Top comments (0)