# Workspace Architecture

Milestone 4.1 introduces Sapling's first filesystem-backed workspace experience.

## Source Of Truth

A workspace is a folder on disk.

Sapling does not create workspace manifests, project registries, content databases, or any other authoritative copy of workspace contents. The application may persist UI and application settings, such as the last opened workspace path, but the filesystem remains the source of truth for folders, files, and projects.

Workspace contents are discovered from the selected root directory and kept as an in-memory presentation tree. That tree can be rebuilt from the filesystem.

## Filesystem Scanning

`LocalWorkspaceManager` scans one directory level at a time and derives:

- folders from directories
- files from regular filesystem items
- projects from directories containing `.git`

Hidden files and `.git` internals are excluded from the visible tree. Project directories remain browsable tree nodes, but they are visually distinguished from ordinary folders.

The scanner performs no Git operations. Repository detection is based only on filesystem metadata.

## Lazy Discovery

Workspace opening loads only the root directory level. Folder and project children are loaded when the user expands that tree node.

```text
Open Workspace
-> scan root directory only
-> display root items
-> expand folder
-> scan that folder only
```

Collapsed folders do no filesystem work. Previously, eager recursive scanning made initial workspace opening and large folder expansion feel slow because large portions of the workspace were discovered before the user asked to see them. The lazy strategy keeps initial display bounded by the size of the root directory and moves deeper discovery to explicit expansion.

The application model stores loaded children by standardized folder URL. This cache is UI state, not authoritative workspace metadata. If the tree needs to be refreshed, it can be rebuilt from the filesystem.

Filesystem scanning is dispatched away from the main actor so the UI can show loading feedback immediately.

## Workspace Tree

The workspace tree answers:

> What exists?

It represents the current filesystem hierarchy and should not own editor state, cursor position, scroll position, unsaved changes, or tab state.

The sidebar uses the derived tree to display folders, Markdown files, other files, and Git-backed projects. Folder and project nodes are collapsible so large hierarchies can be browsed incrementally.

Expanding a folder shows a lightweight loading row while that directory is scanned. Tree insertion animations are disabled because large animated insertions made expansion feel slower and visually noisy.

Rows are sorted with folders and projects first, then files. Each group uses localized alphabetical ordering. Git repositories participate in folder ordering but keep project styling.

Example:

```text
Docs
Sapling
Tests
README.md
ROADMAP.md
```

## Document Sessions

Document sessions answer:

> What is open?

`DocumentSessionStore` owns open Markdown document sessions independently from the workspace tree. Each session owns its `HybridMarkdownEditorViewModel`, which contains editor state for the document.

A file may only have one document session within the active workspace. Opening an already-open Markdown file activates the existing session instead of creating a duplicate editor state.

Opening a new workspace clears document sessions from the previous workspace.

## Persisted State

Sapling persists the last opened workspace URL in `SaplingConfiguration`.

It does not persist workspace contents. Files, folders, and projects are always rediscovered from disk.