Sapling/decisions.md

# DECISIONS

This document records major architectural and product decisions made during the development of Sapling.

The goal is to preserve context and reasoning behind decisions so future contributors can understand why a particular approach was chosen.

---

# D-001 — Sapling Is Local-First

Date: 2025-08

Status: Accepted

## Decision

Sapling will be a local-first application.

All user content lives on the local filesystem.

No Sapling-managed cloud service will be required.

## Rationale

Users should own their data.

Files must remain accessible outside of Sapling.

The application should continue functioning without network connectivity.

## Consequences

Positive:

- No vendor lock-in
- Offline support
- Simpler privacy story
- Easier long-term maintenance

Negative:

- No built-in synchronization
- Collaboration relies on Git workflows

---

# D-002 — Git Is Infrastructure, Not the Product

Date: 2025-08

Status: Accepted

## Decision

Git will be a first-class capability but not the primary user-facing concept.

The editor and workspace experience take precedence over Git terminology.

## Rationale

Most users want versioning benefits without learning Git internals.

Sapling should remain approachable to writers, researchers, and knowledge workers.

## Consequences

User interfaces should prefer language such as:

- Snapshot
- Changes
- History

over:

- Commit
- Staging
- Reflog

Advanced Git functionality will remain available.

---

# D-003 — Projects Are Git Repositories

Date: 2025-08

Status: Accepted

## Decision

Every Sapling project corresponds directly to a Git repository.

No custom repository format will be introduced.

## Rationale

Git repositories are portable and understood by existing tooling.

Users should be able to move between Sapling and other Git tools without migration.

## Consequences

Projects can be opened in:

- Terminal
- GitHub Desktop
- SourceTree
- VS Code
- Any Git client

without conversion.

---

# D-004 — Workspaces Are Not Versioned

Date: 2025-08

Status: Accepted

## Decision

Workspaces are organizational containers and are not Git repositories.

Projects are versioned.

Workspaces are not.

## Rationale

Users need a place for temporary notes, drafts, and experimentation.

Not everything should require commits.

## Consequences

Workspace structure exists outside repository history.

Projects remain independently portable.

---

# D-005 — Attachments Belong to Projects

Date: 2025-08

Status: Accepted

## Decision

Attachments are stored inside project directories.

They are not stored in a database.

They are not stored in a global asset store.

## Rationale

Repositories should remain self-contained.

Cloning a repository should retrieve everything required to render its content.

## Consequences

Projects remain portable.

Attachments participate naturally in version control.

---

# D-006 — Large Assets Use Git LFS

Date: 2025-08

Status: Accepted

## Decision

Large binary files should be managed through Git LFS.

## Rationale

Repositories containing images, PDFs, design assets, and media files can become excessively large.

Git LFS is the industry-standard solution.

## Consequences

Sapling must detect and assist with LFS configuration.

---

# D-007 — Subprojects Use Git Submodules

Date: 2025-08

Status: Accepted

## Decision

Nested projects are implemented using Git submodules.

## Rationale

Submodules provide an existing, portable, Git-native solution.

No custom dependency system is required.

## Consequences

Sapling must provide a significantly better UX around submodules than traditional Git tools.

---

# D-008 — Hybrid Markdown Editing Is a Core Feature

Date: 2025-08

Status: Accepted

## Decision

Sapling will implement hybrid Markdown editing.

The active line displays source.

Inactive lines display rendered content.

## Rationale

This editing model combines the readability of rendered Markdown with the precision of source editing.

It is one of the primary differentiators of Sapling.

## Consequences

The editor becomes a critical architectural component.

Prototype and validation work should occur early.

---

# D-009 — The Editor Is the Highest-Priority System

Date: 2025-08

Status: Accepted

## Decision

Editor quality takes precedence over Git features.

## Rationale

Users tolerate missing Git features.

Users do not tolerate poor editing experiences.

## Consequences

Development milestones should prioritize:

1. Editing
2. Rendering
3. Workspace management
4. Git integration

in that order.

---

# D-010 — Git Access Must Be Abstracted

Date: 2025-08

Status: Accepted

## Decision

All Git functionality must be accessed through a GitProvider abstraction.

Application code should never invoke Git directly.

## Rationale

macOS and iOS have different implementation requirements.

A clean abstraction improves portability and testability.

## Initial Implementations

MacGitProvider

- Uses system Git

EmbeddedGitProvider

- Future iOS implementation

## Consequences

All repository operations must remain implementation-agnostic.

---

# D-011 — Markdown Files Remain Standard Markdown

Date: 2025-08

Status: Accepted

## Decision

Sapling documents are standard Markdown files.

No proprietary format will be introduced.

## Rationale

Users should be free to edit documents with any editor.

Knowledge should not be trapped inside Sapling.

## Consequences

Any Sapling-specific features should degrade gracefully in standard Markdown environments.

---

# D-012 — Platform Focus

Date: 2025-08

Status: Accepted

## Decision

macOS is the primary target platform.

iOS support is a secondary objective.

## Rationale

The desktop writing experience is the primary use case.

Starting with macOS reduces complexity and accelerates development.

## Consequences

Architecture should remain cross-platform where practical.

Product decisions should optimize for desktop workflows first.