XBuckle project files

Document model

Three units, clear jobs

Unit	Form	Role
Config	xbuckle.config.json	Complete non-data config: services, providers, ports, schema (tables/columns/indexes), optional data pointer. Project name lives inside JSON (not the filename).
Data	*.xbudb	Complete instance data (DB rows + other service payloads).
Document	*.xbu	ZIP of config + data. Config is the index; data is the payload.

Legacy still readable: .xbuj / .xbujson, .xbujd/, pg.dump, .xbudump.

---

Open / load rules

Action	Behavior
Open xbuckle.config.json	Create/activate project from config. Data stored in app storage. Config file is live-updated when the project is saved. If data.file / data.url is set (relative/absolute/https://), try to load with progress; toast on failure.
Open *.xbu	Create project and load data. Source .xbu is never modified. Config + data copy live under XBuckle app data.
Open / Load *.xbudb alone	Load Data only (needs an open project). Does not create a profile. Schema misalignment → error. Existing data → Merge / Overwrite confirm.
Open Folder (legacy .xbujd)	Compat package dir; prefers xbuckle.config.json, else {name}.xbuj + database/pg.dump.

---

Config JSON shape

{
  "kind": "xbuckle.config",
  "version": 2,
  "name": "origin-web",
  "services": ["auth", "database", "s3"],
  "providers": { "s3": "r2" },
  "ports": { "proxy": 3110, "pg": 5442 },
  "schema": {
    "engine": "postgres",
    "tables": [
      {
        "schema": "public",
        "name": "profiles",
        "columns": [
          { "name": "id", "type": "uuid", "pk": true },
          { "name": "email", "type": "text", "nullable": false }
        ]
      }
    ]
  },
  "seeds": {
    "authUsers": [{ "email": "admin@origin.local", "password": "password" }],
    "storageBuckets": [{ "id": "avatars", "public": true }],
    "s3Buckets": ["assets"],
    "flags": [{ "key": "checkout-v2", "value": true, "rollout": 50 }],
    "queues": [{ "name": "orders-queue" }]
  },
  "data": {
    "file": "./origin-web.xbudb",
    "onOpen": "ask"
  }
}

Without .xbudb, open config must still work:

1. config:bootstrap → handler from seeds (auth clients/users, empty buckets, flags, queues)
2. Fresh PGlite without demo starter tables when schema present
3. Apply schema DDL → empty tables PostgREST can query
4. Dependent services do not break for lack of rows — only empty result sets

---

Storage semantics

How opened	Config write-back	Data location
xbuckle.config.json	Yes — save updates that file	App-managed working data (and linked .xbudb if user Load Data / writeBack)
*.xbu	No — never touch source zip	App data dir only
Load Data .xbudb	N/A	Into current project runtime

---

Redundancy (compat only)

Not target SSOT (still may appear during migration):

• handler.json as a third peer of config+data
• {name}.xbuj filename as project identity
• Nested multi-file layouts beyond config + xbudb

---

Implementation status

• [x] xbuckle.config.json / .xbudb / .xbu constants & path helpers
• [x] Load Data accepts .xbudb + legacy dump
• [x] .xbu ZIP writes xbuckle.config.json + data.xbudb
• [x] File associations + icons for .xbudb
• [x] Schema introspect → write into config on save
• [x] Apply schema when opening config without data (empty public schema)
• [x] Open .xbu materializes into app userData/workspaces/ (immutable source)
• [x] Schema alignment check on Load Data (desired config.schema vs dump)