Initial planning docs: CLAUDE.md and ADRs 0000-0008
Captures up-front design decisions for RDBMS Playground: stack (Rust + Ratatui + SQLite), input modes, project file format, type vocabulary, undo snapshots and replay log, sharing/export, and testing approach. ADR-0000 establishes the ADR practice itself and mandates index upkeep alongside any ADR change.
This commit is contained in:
@@ -0,0 +1,59 @@
|
||||
# ADR-0007: Sharing and export
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Learners and instructors will want to share projects: an
|
||||
instructor distributing an exercise, a student attaching a
|
||||
project to a question, a collaborator sending a snapshot.
|
||||
|
||||
The need is real, but committing to a hosted "publish" feature
|
||||
(account system, server, namespace, moderation) would dwarf the
|
||||
core app and is not warranted for a teaching tool. We can satisfy
|
||||
the need entirely with local artifacts and documentation.
|
||||
|
||||
## Decision
|
||||
|
||||
No hosted publishing feature. Sharing is supported via two
|
||||
mechanisms:
|
||||
|
||||
1. **`export` command.**
|
||||
- Available as an app-level command in both input modes
|
||||
(ADR-0003).
|
||||
- Produces a single zip file containing `project.yaml`,
|
||||
`data/`, and `history.log`, **excluding** `playground.db`
|
||||
(the recipient rebuilds it on open per ADR-0004).
|
||||
- Default output path is the parent directory of the project.
|
||||
- Default filename:
|
||||
`YYYYMMDD-<projectname>-export-<sequence>.zip`, where
|
||||
`YYYYMMDD` is today's local date and `<sequence>` is a
|
||||
two-digit zero-padded counter that starts at `01` and is
|
||||
incremented to avoid clobbering an existing file in the
|
||||
output directory on the same day.
|
||||
- An explicit path and/or filename may be given to override
|
||||
the default.
|
||||
|
||||
2. **Documented recipes.**
|
||||
- Each new project includes a `.gitignore` template that
|
||||
excludes `playground.db`, so committing a project to git
|
||||
yields a clean, diff-friendly history.
|
||||
- The user-facing documentation includes recipes for sharing
|
||||
via git, email, and direct file transfer.
|
||||
|
||||
If real-world usage later reveals friction these mechanisms cannot
|
||||
solve, a publish feature can be revisited as a separate ADR.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Zero server-side surface area, zero accounts, zero hosting
|
||||
costs.
|
||||
- Sharing is a power-user-friendly workflow from day one without
|
||||
blocking on infrastructure decisions.
|
||||
- Recipients reconstruct the database deterministically from the
|
||||
authoritative text sources — sharing is automatically a
|
||||
validation of the rebuild path.
|
||||
- If a future hosted feature is ever added, this ADR is
|
||||
superseded, not extended.
|
||||
Reference in New Issue
Block a user