🏔️ MarkVault

MarkVault is a premium, offline, local-first markdown knowledge base built natively for macOS with Swift 6.0, SwiftUI, and the Apple App Sandbox.

It features seamless [[wikilink]] navigation, a custom high-performance regex markdown scanner, active file watching, debounced atomic saving, concurrent background indexing, an interactive spring-physics visual thought map, fuzzy autocompletes, daily notes journaling, and an active-recall study review module based on the SuperMemo-2 (SM-2) spaced repetition algorithm.

---

✨ Features

• Local-First & Private: Strict App Sandbox enforcement with 0 network calls ensures all files reside completely and securely on your local machine.
• Wikilink Navigation: Standard [[wikilink]] and [alias|wikilink] link scanning. Clicking a link resolves and navigates instantly. If the destination note does not exist, a placeholder note is created automatically.
• Fuzzy Autocomplete Tooltips: Typing [[ inside the editor opens a popover suggestions list that fuzzy-filters note titles and tag metadata in real-time, offering a one-click action to create a new note if it doesn't exist.
• Daily Notes Journaling (⌘D): Instantly creates or opens today's journal entry pre-templated with structured headings for Goals, Thoughts, and Tasks, categorized under #daily and #journal.
• Spaced Repetition Review Decks: Scans notes for cards (lines ending in #card or #flashcard). Clicking "Review Decks" triggers an active study session where you can reveal answers and grade recall ease (0-5) using the native SuperMemo-2 (SM-2) algorithm. Decks interval progress is saved locally inside .markvault/spaced_repetition.json.
• Interactive Visual Thought Maps: An interactive canvas that draws a live 2D spring-physics layout mapping note nodes and wikilink connections, with gesture support for dragging nodes.
• Modern Concurrency: Isolated on @MainActor thread safety, offloading heavy scans, text processing, and indexing to concurrent background pools (TaskGroup).
• Premium Aesthetics: Glassmorphic sidebar materials (NSVisualEffectView), system accent-color matching, and segmented view layout modes (Editor, Preview, Split, or Graph).

---

🏗️ Technical Architecture

graph TD
    A[Vault Folder] -->|Scan & Watch| B(FileStore / FileWatcher)
    B -->|Raw Markdown Content| C(Parser)
    C -->|Parsed AST / Metadata / Links| D(Indexer)
    D -->|Index Update| E(VaultState)
    E -->|Single Source of Truth| F(SwiftUI Layout / NavigationSplitView)
    F -->|User Interaction / Edit| E
    E -->|Debounced Write| B

Loading

• FileStore: Manages atomic reads and writes (writing to temporary files and swapping) under sandbox directory constraints.
• Parser: Extracted via NSRegularExpression scanning frontmatter YAML variables, wikilinks, and flashcard card triggers.
• Indexer: Computes backlinks concurrently in the background. Persists indices inside .markvault/index.json.
• FileWatcher: Streams file-system changes in notes/ directory using macOS DispatchSourceFileSystemObject to present live conflict banners for external modifications.
• VaultState: The @Observable central coordinator managing state.

---

🛠️ Build, Run & Testing

1. Requirements

• macOS 14+ (Sonoma or Sequoia)
• Apple Silicon (or Intel Mac)
• Swift 5.9+ / 6.0 (Command Line Tools are sufficient, Xcode is not required)

2. Compile & Launch Application Bundle

To compile and package the release application into a standalone sandboxed desktop bundle:

# 1. Compile release binary and construct bundle
./package.sh

# 2. Launch the desktop app
open build/MarkVault.app

Alternatively, run swift run markvault to launch the debugging executable context.

3. Run Custom Integration Testing Suite

MarkVault runs a lightweight executable-based test runner that executes 14 asynchronous assertions covering FileStore atomicity, parser, indexer, SM-2 calculations, and navigation life cycles:

# Run unit tests
swift run markvault-tests

4. Execute 8-Phase QA Integration Pipeline

We provide a master testing script that verifies the full compiler sanity, unit test completion, app packaging folder checks, sandbox codesign verification, and mock vault export validations:

./run_integration_tests.sh

---

🗃️ Data Schema

When you open a folder as a vault, MarkVault creates the following structure:

Vault Root/
  notes/
    welcome.md
    features.md
  .markvault/
    index.json             # Cached page mappings and backlink indices
    settings.json          # Vault-specific theme configurations
    spaced_repetition.json # SuperMemo-2 card ratings database

Markdown Specification

---
title: Welcome to MarkVault
created: 2026-06-02T00:00:00Z
tags: [welcome, guide]
---
# Welcome to MarkVault 🏔️

This is content containing [[Features]] links.

What are the structural features of MarkVault? #flashcard
- Obsidian-style wikilinks navigation
- Local-first sandbox architecture