352 lines
5.9 KiB
Markdown
352 lines
5.9 KiB
Markdown
# 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.
|