claude@clouddev1
3a0c03d781
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.
82 lines
3.5 KiB
Markdown
82 lines
3.5 KiB
Markdown
# RDBMS Playground — project notes for Claude
|
|
|
|
## What this project is
|
|
|
|
A cross-platform TUI application that gives learners a sandbox for
|
|
exploring relational database concepts: tables, columns, primary
|
|
and foreign keys, relationships, indexes, queries, and query
|
|
plans. The audience is students from beginners to those ready for
|
|
raw SQL, and the design accommodates both ends of that spectrum.
|
|
|
|
The application is a teaching tool, not a database administration
|
|
tool. Decisions about the type system, command surface, and
|
|
backend choices are skewed toward pedagogy over breadth.
|
|
|
|
## Authoritative decisions
|
|
|
|
All significant design decisions live in `docs/adr/`. Read
|
|
`docs/adr/README.md` for the index. **Before proposing changes
|
|
that touch a decided area, read the relevant ADR.** Decisions are
|
|
not re-litigated casually — if a decision needs to change, write a
|
|
new ADR that supersedes the old one.
|
|
|
|
Current decisions at a glance (each backed by an ADR):
|
|
|
|
- **Stack:** Rust + Ratatui + Crossterm; `sqlparser-rs` for SQL,
|
|
`rusqlite` for the database (ADR-0001).
|
|
- **Backend:** SQLite with `STRICT` tables and FK enforcement on
|
|
(ADR-0002).
|
|
- **Input:** simple mode (DSL only) by default; advanced mode
|
|
(SQL + app-level commands) on toggle; `:` one-shot escape from
|
|
simple to advanced (ADR-0003). No other sigils.
|
|
- **Project format:** `project.yaml` + `data/<table>.csv` +
|
|
`history.log`; `playground.db` is a derived artifact (ADR-0004).
|
|
- **Types:** `text`, `int`, `real`, `decimal`, `bool`, `date`,
|
|
`datetime`, `blob`, `serial`, `shortid`. Compound primary keys
|
|
supported. No real UUIDs (ADR-0005).
|
|
- **Safety:** auto-snapshot before destructive ops; `:undo`;
|
|
append-only `history.log` for replay and scripting (ADR-0006).
|
|
- **Sharing:** `export` command produces a zip without the `.db`;
|
|
no hosted publishing (ADR-0007).
|
|
|
|
## Repository layout (planned)
|
|
|
|
The repository is in early planning. Once code lands, layout
|
|
conventions will be added here. For now, `docs/adr/` is the
|
|
canonical source of decided ground.
|
|
|
|
## Working style for this project
|
|
|
|
- **Documentation discipline.** Significant decisions get an ADR.
|
|
In-flight discussion stays in conversation or issues until it
|
|
settles.
|
|
- **Testing.** Per the user's global standards, tests are
|
|
established before changes, bugs are reproduced with failing
|
|
tests before being fixed, and "all green, no skips" is the only
|
|
acceptable end state. Integration tests exercise full flows
|
|
(e.g. project save → reload → rebuild produces the same
|
|
observable database), not just units in isolation.
|
|
- **No silent feature loss.** Anything in an ADR is decided. If
|
|
implementation reveals that a decision is wrong or impractical,
|
|
raise it explicitly and update the ADR — do not quietly drift.
|
|
- **Pedagogy wins ties.** When a design choice trades clarity for
|
|
raw capability, prefer clarity. Real RDBMS power-user features
|
|
exist; this app is not the place to teach them.
|
|
|
|
## Things deliberately deferred
|
|
|
|
These have been discussed but not yet decided. Do not implement
|
|
ahead of an ADR for any of them:
|
|
|
|
- Tutorial / lesson system architecture (acknowledged as in scope
|
|
for design; needs its own ADR before code).
|
|
- Query plan rendering specifics (the *what* is decided — annotated
|
|
tree view of `EXPLAIN QUERY PLAN`; the *how* is not).
|
|
- Friendly error message rewriting layer (decided to exist; design
|
|
not done).
|
|
- Sample data generation rules, including FK-aware generation for
|
|
junction tables.
|
|
- Visual ER diagram export.
|
|
- DSL grammar specifics (compound key syntax, m:n relationship
|
|
command, etc.).
|