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