lumi

A local-first, markdown-based note-taking system. v2 is multi-tenant and collaborative: an Obsidian-style vault is either fully local or bound to a self-hosted server with live Yjs CRDT sync. The filesystem (markdown + YAML frontmatter) stays the source of truth on disk; the server projects it through a CRDT for real-time collaboration.

Full v2 spec: SPEC.md · Docs site: lumi-note.vercel.app/#/docs

Architecture

┌─────────────────┐  ┌──────────────┐  ┌──────────────────┐
│   TUI Client    │  │  Web Client  │  │   Apple Client   │
│ (Go + Bubbletea)│  │  (Svelte 5)  │  │    (SwiftUI)     │
└────────┬────────┘  └──────┬───────┘  └────────┬─────────┘
         │                  │                   │
  snapshot+diff       Yjs WS + REST       Yjs WS + REST
  REST sync           (live awareness)    (yswift + presence)
         │                  │                   │
         └──────────────────┼───────────────────┘
                            │
                  ┌─────────▼──────────┐
                  │  lumi-server (v2)  │
                  │  Fiber + cgo yrs   │
                  └─────────┬──────────┘
                            │
              ┌─────────────┴────────────┐
              │                          │
       ┌──────▼──────┐         ┌─────────▼─────────┐
       │  Postgres   │         │   Filesystem      │
       │ users/vaults│         │  <vault>/notes/   │
       │ roles/audit │         │  Markdown + YAML  │
       │ Yjs state   │         │ (source of truth) │
       └─────────────┘         └───────────────────┘

• Vault = unit of work. Portable directory containing notes + a .lumi/ metadata folder. Local-only or bound to a server. Sync is opt-in per vault.
• Multi-tenant server. Fiber + Postgres host many vaults with per-vault custom roles, invite-link signup, session auth.
• Yjs CRDT drives live collaboration. Web and Apple clients exchange Yjs updates + awareness/presence over WebSocket. TUI uses snapshot+diff REST (no live cursors — $EDITOR is opaque).
• FS-CRDT bridge. External markdown edits are detected via fsnotify and diff-merged into the CRDT, then broadcast to all subscribers.

Repository

Each component is a separate repo, linked here as a git submodule:

Clone

git clone --recurse-submodules [email protected]:ViniZap4/lumi.git

If already cloned without submodules:

git submodule update --init --recursive

The server depends on third_party/y-crdt (a submodule of lumi-server); the recursive flag is required.

Prerequisites

Optional TUI media: timg, chafa, viu for images; ffmpeg for video thumbnails.

Quick Start

Docker Compose (recommended)

cp .env.example .env                       # edit POSTGRES_PASSWORD, LUMI_ADMIN_*
git submodule update --init --recursive
docker compose up -d

# Web UI: http://localhost:3000
# API:    http://localhost:8080

On first boot, if LUMI_ADMIN_USERNAME + LUMI_ADMIN_PASSWORD are set and the users table is empty, the server seeds a single admin account. Otherwise, sign up via an invite link.

VITE_LUMI_SERVER_URL is baked at image build time. After changing LUMI_SERVER_URL, rebuild: docker compose build web.

Server (standalone)

cd server
git submodule update --init --recursive    # pulls third_party/y-crdt
make libyrs                                 # builds libyrs.a via cargo
docker compose up -d postgres               # local Postgres on :5432
make migrate                                # apply migrations
make run                                    # http://localhost:8080

Web client (standalone)

cd web-client
npm install
npm run dev                                 # http://localhost:5173

TUI client

cd tui-client
go build -o lumi
./lumi                                      # vault picker if vaults registered
./lumi ../vaults/personal                   # open a local vault
./lumi login https://lumi.example.com       # sign in to a server
./lumi vault clone https://lumi.example.com/personal
./lumi vault manage                         # interactive vault TUI

Apple client

cd apple-client
make bootstrap
make open                                   # opens Xcode

Environment Variables

Server (docker compose / lumi-server)

Web client

Compose

See .env.example for the complete list.

Note Format

---
id: my-note-id
title: My Note Title
created_at: 2026-02-16T10:00:00Z
updated_at: 2026-02-16T10:00:00Z
tags:
  - example
---

# My Note Title

Markdown body with wiki-links: `[[other-note-id]]`.

Plain markdown files (no frontmatter) are accepted — lumi preserves the on-disk format on save unless metadata is explicitly added through the UI.

API

REST + WebSocket served by lumi-server. Full surface and protocol live in SPEC.md (API surface section).

Auth is session-based: POST /api/auth/login returns a session cookie + token; subsequent calls send X-Lumi-Token (REST) or ?token= (WS). Per-vault custom roles gate every mutation; the seed roles are Admin / Editor / Viewer / Commenter.

Pillars

Applied to every design decision, in order: Security/LGPD → performance → DX → scale → UX → UI → QA. LGPD compliance is a hard constraint.

License

MIT

Credits

Built with Fiber, Bubbletea, Svelte, CodeMirror, Yjs / y-crdt, and Go.