Database

Flat-File Architecture

Self-hosted LiveFolio stores all data in a single file: database.json at the project root. No database server is required.

Structure

[
  {
    "id": "my-folio-1234",
    "title": "My Folio",
    "description": "A sample folio",
    "createdAt": "2026-06-15T10:00:00Z",
    "updatedAt": "2026-06-15T10:30:00Z",
    "comments": [],
    "projectMode": "document",
    "designPreferences": {},
    "versions": [
      {
        "versionId": "v1",
        "commitMessage": "Initial publish",
        "createdAt": "2026-06-15T10:00:00Z",
        "author": "User",
        "files": {
          "index.html": "<!DOCTYPE html>...",
          "assets/style.css": "body { ... }"
        }
      }
    ]
  }
]

File Locking

Concurrent writes are protected by file-based advisory locking. When a write is in progress:

1. A .lock file is created
2. Other write attempts wait for the lock to release
3. The lock releases automatically when the write completes

This prevents data corruption from concurrent CLI sync and dashboard edits.

Performance

The flat-file approach is suitable for:

• Up to ~100 folios (single JSON parse is fast)
• Up to ~50 versions per folio (file stays under 10 MB)
• Single user access (no concurrent read/write contention)

For larger workloads, consider migrating to a hosted database.

Backups

Manual

cp database.json database.backup.$(date +%Y%m%d).json

Automated

#!/bin/bash
BACKUP_DIR="./backups"
mkdir -p "$BACKUP_DIR"
cp database.json "$BACKUP_DIR/database.$(date +%Y%m%d-%H%M%S).json"
ls -t "$BACKUP_DIR"/database.*.json | tail -n +31 | xargs rm -f

Add to cron:

0 3 * * * /path/to/backup.sh

What to Back Up

• database.json — all folio data (the one that matters)
• settings.json — MCP master key and tunnel config

That's the whole state. Provider keys live in your browser (or an optional .env you created yourself), and the app itself is replaceable.

Migration

To move your folios out of a self-hosted instance:

1. Stop the server
2. Copy the database: cp database.json /tmp/export.json
3. Import it wherever you're going, using that target's import path
4. Verify your folios appear there
5. Archive the original database.json

There is no proprietary export format — database.json is plain JSON, so your folios are readable with or without LiveFolio.

Disaster Recovery

If database.json is corrupted:

# Stop the server
# Restore from backup
cp database.backup.YYYYMMDD.json database.json
# Restart
npm run dev

Prevention:

• Don't manually edit database.json while the server is running
• Use the API or MCP for all data modifications
• Keep regular automated backups