Database

How the flat-file JSON database works in self-hosted LiveFolio — structure, locking, backups, and migration.

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:

A .lock file is created
Other write attempts wait for the lock to release
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
settings.json — MCP key and tunnel config
.env — API keys and configuration

Migration

To migrate from self-hosted to a hosted database:

Stop the server
Export your data: cp database.json /tmp/export.json
Import into your hosted database using its import tools
Update .env accordingly
Verify all folios appear in the dashboard
Archive the old database.json

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