···11+# CLAUDE.md
22+33+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
44+55+## Project Overview
66+77+Node.js/TypeScript benchmark suite comparing local datastore performance (TinyBase, LevelGraph, SQLite) with ~1GB test data. Each benchmark runs 10 iterations, discards high/low scores, and reports the median.
88+99+## Commands
1010+1111+```bash
1212+npm install # Install dependencies
1313+npm run generate # Generate test data (~1GB) to test-data/
1414+npm run bench # Run benchmarks on all stores (10 iterations each)
1515+npm run bench:store tinybase # Benchmark single store
1616+npm run bench:store levelgraph
1717+npm run bench:store sqlite
1818+npm run charts # Regenerate charts from latest results
1919+```
2020+2121+## Architecture
2222+2323+- `src/generator/` - Test data generation (URLs, images, documents, metadata)
2424+- `src/harness/` - Benchmark runner, timing, and result reporting
2525+- `src/stores/` - Datastore adapters implementing `DatastoreAdapter` interface
2626+- `src/runner.ts` - Main CLI entry point
2727+2828+## Adding a New Datastore
2929+3030+1. Create `src/stores/yourstore.ts` implementing `DatastoreAdapter` from `src/harness/types.ts`
3131+2. Register in `src/stores/index.ts`
3232+3333+The adapter interface requires: `init()`, `cleanup()`, `addUrls()`, `addImage()`, `addDocument()`, `addMetadata()`, `getRecentUrls()`, `getImages()`, `getDocuments()`, `getDiskUsage()`
+77
README.md
···11+# localstress
22+33+Benchmark suite for comparing local datastore performance in Node.js.
44+55+## Quick Start
66+77+```bash
88+npm install
99+npm run generate # Generate ~1GB test data (takes a few minutes)
1010+npm run bench # Run benchmarks on all stores
1111+```
1212+1313+## Datastores Tested
1414+1515+- **TinyBase** - Reactive data store for local-first apps
1616+- **LevelGraph** - Graph database built on LevelDB
1717+- **SQLite** - Embedded SQL database (via better-sqlite3)
1818+1919+## Methodology
2020+2121+Each benchmark is run **10 times** per datastore. The highest and lowest scores are discarded, and the **median** of the remaining 8 runs is reported. This reduces the impact of outliers from system variability.
2222+2323+## Test Dataset
2424+2525+Target ~1GB total:
2626+2727+- 10,000 URLs with metadata
2828+- 1,000 PNG images (~900MB)
2929+- 1,000 text documents (~50MB)
3030+- 100,000 metadata rows
3131+3232+## Benchmarks
3333+3434+**Init**
3535+- Store initialization time
3636+3737+**Writes**
3838+- Add all URLs
3939+- Add all metadata rows
4040+- Add all images
4141+- Add all documents
4242+4343+**Reads**
4444+- Get 100 most recent URLs
4545+- Get 10 random images
4646+- Get 1000 random documents
4747+4848+**Disk**
4949+- Total storage space used
5050+5151+## Commands
5252+5353+```bash
5454+npm run generate # Generate test data to test-data/
5555+npm run bench # Benchmark all stores (10 iterations each)
5656+npm run bench:store tinybase # Benchmark single store
5757+npm run bench:store levelgraph
5858+npm run bench:store sqlite
5959+npm run charts # Regenerate charts from latest results
6060+```
6161+6262+## Adding a New Datastore
6363+6464+1. Create `src/stores/yourstore.ts` implementing `DatastoreAdapter` from `src/harness/types.ts`
6565+2. Register in `src/stores/index.ts`
6666+6767+## Project Structure
6868+6969+```
7070+src/
7171+ generator/ # Test data generation
7272+ harness/ # Benchmark runner and reporting
7373+ stores/ # Datastore adapters
7474+ runner.ts # CLI entry point
7575+test-data/ # Generated test data (gitignored)
7676+results/ # Benchmark results JSON (gitignored)
7777+```