Skip to content

Architecture & data model

This page describes how Tessera is put together and how your projects are stored on disk. It is aimed at contributors and curious users, not at day-to-day editing (see the Features section for that).

Repository layout (high level)

Area Role
tauri-desktop/ Desktop app (Tauri v2): Rust shell + Vite/HTML/CSS/JS UI, filesystem access via Tauri plugins and commands.
src-docs/ User documentation sources (MkDocs); can be opened as a Tessera vault.
docs/ Static site root for GitHub Pages (landing + generated guide/).

The shipped product is the Tauri desktop build only. Older browser/Flask prototypes were removed from the tree; history remains in git.

What is a “project”?

A project (vault) is a single directory on your computer. Tessera never hides your notes behind a database: everything is ordinary files.

Typical layout:

my-project/
├── order.json      # Order of note cards on the grid (note IDs)
├── tags.json       # Map of note ID → list of tag strings
├── note_one.md     # Markdown body for note_one
├── note_one/       # Images attached to note_one (optional)
│   └── diagram.png
└── note_two.md
  • order.json — JSON object with an "order" array of note IDs (strings without .md). Tessera creates or repairs this file if it is missing or out of sync with .md files on disk.
  • tags.json — JSON object whose keys are note IDs and whose values are arrays of tag labels (with optional color metadata in the app’s format).
  • <id>.md — One Markdown file per note; the note ID is the filename without extension. Characters must be safe for the filesystem (the app validates names when you create notes).
  • <id>/ — Optional folder named after the note; image files placed here are associated with that note in the UI.

How the UI talks to data

The embedded web UI calls tauri-desktop/src/api.js (and related modules), which read and write files under the active project path using Tauri’s filesystem APIs and Rust commands in src-tauri/src/lib.rs.

Operations include: list projects, list notes, read/update Markdown, persist order and tags, accept image uploads into the correct note folder, and open folders in the OS file manager.

Markdown and preview

Note bodies are plain Markdown. The app renders a preview after save (and in context on the card). Rendering uses DOMPurify on parsed HTML, with a plain-text fallback if the sanitizer is unavailable. Image references in Markdown are resolved relative to the project so that previews match the on-disk layout.

Themes

Light and dark themes are driven by CSS custom properties on html / body (e.g. [data-theme="dark"]). The desktop app and the marketing page reuse the same palette tokens so the product and the site feel consistent.