7.4 KiB
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:
- Editing
- Rendering
- Workspace management
- 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.
D-013 — Editor Technology Selection
Date: 2026-05
Status: Accepted Provisionally
Review After: Milestone 2
Decision
Sapling will use native platform text systems for the editor prototype:
- NSTextView on macOS
- UITextView on iOS
These views will be wrapped behind a Sapling editor abstraction.
SwiftUI TextEditor will not be used as the primary editor implementation.
Rationale
Sapling's hybrid Markdown editor requires advanced control over cursor movement, selection state, layout, attributed rendering, and editing behavior.
SwiftUI TextEditor is useful for simple text entry, but it does not expose enough low-level editing hooks to validate the active-line source and inactive-line rendered model cleanly.
NSTextView and UITextView provide direct access to TextKit, attributed text storage, selection ranges, delegates, layout managers, and platform editing behaviors. That makes them better foundations for Milestone 1 validation.
Consequences
Positive:
- The prototype can inspect and control selection ranges directly.
- Line-level styling and rendering experiments can be performed in-place.
- The app can preserve native editing behavior while testing hybrid Markdown concepts.
- The implementation can remain SwiftUI at the application layer.
Negative:
- AppKit and UIKit bridging adds platform-specific code.
- The editor abstraction must prevent the rest of the app from depending directly on NSTextView or UITextView.
- A future custom editor engine may still be required if line replacement or overlay rendering cannot preserve cursor correctness.