Bucket & Entities

The Bucket is the Database

Based doesn't use a traditional database. Instead, every piece of data is a JSON file in an S3-compatible bucket. The S3WORM library provides typed access, schema inference, and CRUD operations on top of flat files.

Bucket Layout

bucket/
├── bases/base_abc.json        # workspace metadata + ACLs
├── users/user_456.json        # user profiles
├── pages/page_xyz.json        # Tiptap documents
├── views/view_123.json        # database block view configs
├── customers/cust_001.json    # your business entities
├── invoices/inv_001.json
└── .worm/                     # s3worm internals
    ├── oplog/                 # immutable mutation log
    ├── trash/                 # soft-deleted entities
    └── snapshots/             # periodic full copies

All collections are peers at the bucket root. The only dotfile prefix is .worm/ for S3WORM library internals (oplog, trash, snapshots).

Entity Structure

Every entity is a JSON file with a stable ID. For example, a page entity:

{
  "id": "page_xyz",
  "baseId": "base_abc",
  "parentPageId": null,
  "title": "My First Page",
  "icon": "📄",
  "content": { /* Tiptap JSON document */ },
  "createdAt": "2026-02-24T00:00:00Z",
  "updatedAt": "2026-02-24T00:00:00Z"
}

Oplog & Recovery

Every mutation (create, update, delete) is logged to the oplog at .worm/oplog/. This provides:

• Full audit trail of every change
• Point-in-time rollback to any previous version
• Soft delete — entities go to trash, recoverable within retention period
• Periodic snapshots for fast reconstruction

Local Development

Set S3_MODE=local in your .env to use the local filesystem at .worm/data/ as your bucket. JSON files are read and written directly — no S3 required.