Files

T

claude@clouddev1 3a0c03d781 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.

2026-05-07 09:27:31 +00:00

3.5 KiB

Raw Blame History

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.).

3.5 KiB Raw Blame History