Simulating the Database: How frankensqlite_website Turns Docs Into a Laboratory

Instead of static architecture diagrams, this Next.js showcase uses WebAssembly and React to let engineers play with B-Trees, WAL lanes, and fountain codes directly in the browser.

7 min read • View on GitHub • More from Dicklesworthstone

A complex mechanical loom enclosed in a glass case, representing a database, with a control panel outside allowing a user to manipulate the gears inside. — The website acts as an interactive viewing window into the complex mechanics of the FrankenSQLite database.

Key Takeaways

The frankensqlite_website repository eschews static markdown for a Next.js application that simulates database internals using React and WebAssembly.
To explain page-level Multi-Version Concurrency Control (MVCC) and RaptorQ durability, the site dynamically imports heavy, state-driven visual components.
The project features a 'Spec Evolution Lab' that loads a real SQLite file into the browser, allowing users to query the history of the design specification.
The website's strict engineering standards, utilizing Bun and Turbopack, mirror the 'Zero Unsafe Rust' philosophy of the underlying database engine.

The Death of the Static Diagram

When building a highly complex, low-level systems tool, explaining how it works is often as challenging as engineering it. For FrankenSQLite—a Rust reimplementation of SQLite designed to solve the single-writer bottleneck—a standard README and some flat SVGs wouldn't suffice. The creator needed to prove that their novel approach to concurrency and durability actually worked.

The solution is frankensqlite_website, a robust Next.js application that treats technical documentation as a living, interactive laboratory. Instead of reading about B-Trees and Write-Ahead Log (WAL) lanes, visitors manipulate them. The /components/viz/ directory houses roughly 30 specialized React components that use state machines to simulate database behaviors in real time.

A simulation of standard SQLite's single-writer lock versus FrankenSQLite's Multi-Version Concurrency Control.

The Single-Writer Bottleneck

To understand why this elaborate website exists, one must understand the ambition of the underlying project. SQLite is ubiquitous, but its architecture has a fundamental limitation for high-throughput applications.

The Problem: SQLite allows only one writer at a time. A single lock byte (`WAL_WRITE_LOCK` at `wal.c:3698`) serializes all writers. For write-heavy workloads, this bottleneck caps throughput regardless of how many cores you have. Torn writes and bit-flips can corrupt the database with no self-repair mechanism.

Dicklesworthstone, Creator · FrankenSQLite Repository

FrankenSQLite aims to replace this file-level lock with page-level Multi-Version Concurrency Control (MVCC) and introduce RaptorQ fountain codes for information-theoretic durability. These are abstract, mathematically dense concepts. The website’s simulation engine is designed specifically to make these mechanics tangible to skeptical engineers.

A Forensic API for the Browser

The most technically ambitious feature of the site is the Spec Evolution Lab located in /app/spec_evolution/. Rather than presenting a static changelog, this section treats the project's specification history as queryable data.

The frontend fetches a .sqlite3 file and loads it into memory using sql.js (SQLite compiled to WebAssembly). Users can write actual SQL queries directly in the browser to explore how the design decisions evolved over time, transforming documentation into a forensic exercise.

A magnifying glass held over a blueprint, where the magnified lines lift off the paper and become 3D puzzle pieces. — The Spec Evolution Lab transforms flat documentation into multi-dimensional, queryable data.

The Simulation Engine Architecture

Building this level of interactivity requires a robust frontend architecture. The visualizations rely heavily on a custom useSimulation hook that drives D3 and ECharts components. To maintain performance, these heavy visual components are dynamically imported, ensuring the initial page load remains fast.

Furthermore, the site employs a centralized content model in lib/content.tsx. This is paired with a "FrankenJargon" system—a glossary mechanism that provides deep-dive tooltips for complex terms without cluttering the high-level marketing copy. It allows the text to remain accessible while offering escape hatches for those who want to inspect the underlying theory.

The "Safe" Philosophy, Full Stack

The engineering rigor of the database is reflected in the website's build process. Just as FrankenSQLite enforces "Zero Unsafe Rust," the web repository mandates strict deterministic builds using Bun and Turbopack. It is a cohesive approach where the medium reinforces the message.

Feature	Traditional Static Docs	FrankenSQLite Simulation Docs
Visuals	Pre-rendered SVGs and PNGs	WASM-driven React components
State	Stateless markdown text	Interactive `useSimulation` state machines
History	Git commit logs and flat changelogs	In-browser SQL querying of spec data
Terminology	Linear glossaries or external links	Contextual "FrankenJargon" overlays

In an era where developer tools are increasingly complex, frankensqlite_website demonstrates that sometimes the best way to explain a system is to build a sandbox and let the user play with the gears.