boardkit-file-format
.boardkit file format: ZIP structure, serialization, versioning, migrations.Use when working on import/export, persistence, or file format changes.
When & Why to Use This Skill
This Claude skill provides a comprehensive technical specification and implementation guide for the .boardkit file format. It covers the internal ZIP archive structure, detailed JSON schemas for metadata and document content, and robust protocols for versioning and data migration. By defining strict serialization rules and storage implementations for both Web (IndexedDB) and Desktop (Tauri) environments, it ensures high data integrity, deterministic output, and seamless backward compatibility for developers working on persistence layers.
Use Cases
- Case 1: Implementing robust import/export functionality for .boardkit files in web or desktop applications, ensuring full compliance with the ZIP and JSON structure.
- Case 2: Developing automated migration scripts to upgrade legacy document versions (e.g., v0 or v1) to the latest schema without data loss.
- Case 3: Optimizing data persistence layers using deterministic serialization and atomic write operations to prevent file corruption during save cycles.
- Case 4: Setting up rigorous file validation pipelines to check size constraints, ZIP integrity, and schema validity before processing user-uploaded content.
| name | boardkit-file-format |
|---|---|
| description | | |
| .boardkit file format | ZIP structure, serialization, versioning, migrations. |
| allowed-tools | Read, Grep, Glob |
Boardkit File Format
Structure
.boardkit = ZIP archive containing:
my-board.boardkit (ZIP)
├── package.json → Metadata
└── board.json → Document content
package.json
{
"name": "my-board",
"version": "1.0.0",
"boardkit": {
"formatVersion": 2
}
}
board.json
{
"version": 2,
"meta": {
"title": "My Board",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-02T00:00:00Z"
},
"board": {
"viewport": { "x": 0, "y": 0, "zoom": 1 },
"widgets": [...],
"elements": [...],
"background": { "type": "dots", "color": "#f5f5f5" }
},
"modules": {},
"dataSharing": {
"permissions": [],
"links": []
}
}
Constraints
| Constraint | Value |
|---|---|
| Max file size | 50 MB |
| Compression | DEFLATE level 6 |
| Extension | .boardkit |
| JSON encoding | UTF-8 |
Document Versions
| Version | Changes |
|---|---|
| v0 | Initial: widgets only |
| v1 | Added: elements[], background |
| v2 | Added: dataSharing section |
Migration Functions
// packages/core/src/migrations/index.ts
function migrateV0ToV1(doc: V0Document): V1Document {
return {
...doc,
version: 1,
board: {
...doc.board,
elements: [],
background: { type: 'dots', color: '#f5f5f5' }
}
}
}
Serialization Rules
Deterministic - Same input = same output
- Sort object keys alphabetically
- No random IDs in output
Atomic writes (Desktop)
- Write to temp file first
- Rename to final path
Transactions (Web/IndexedDB)
- Use IDB transactions
- Rollback on error
Storage Implementations
Web (IndexedDB)
// packages/platform/src/storage/indexeddb.ts
Database: 'boardkit'
Stores: 'documents', 'history'
Autosave: 500ms debounce
History cap: 100 entries
Desktop (Tauri FS)
// apps/desktop/src/composables/usePersistence.ts
Autosave: 1000ms debounce
Atomic writes via temp file
Import Validation
// Required checks on import
1. File size < 50MB
2. Valid ZIP structure
3. package.json exists and valid
4. board.json exists and valid JSON
5. Version supported (migrate if needed)
6. Schema validation
Key Files
| Purpose | Path |
|---|---|
| Document types | packages/core/src/types/document.ts |
| Migrations | packages/core/src/migrations/index.ts |
| Web import/export | apps/web/src/utils/boardkitFile.ts |
| Desktop import/export | apps/desktop/src/utils/boardkitFile.ts |
| IndexedDB storage | packages/platform/src/storage/indexeddb.ts |
| Migration tests | packages/core/__tests__/migrations.test.ts |