HISTORICAL SUPPORTING

This document is preserved for historical context.

🗃️ Kanboard Unified JSON Data Schema

This cheat sheet outlines the exact structure, data merging logic, and best practices for dealing with the unified Kanboard & Feedback JSON export/import format.

🏗️ Core Architecture

The structure is a hybrid payload enabling the single-source-of-truth (SSOT) fusion of both the project management Kanban board and the per-game feedback item boards.

1️⃣ Root Object

{
  "exportedAt": "2026-03-20T02:05:37.129Z",
  "source": "kanboard-unified",
  "board": { ... },    // The global developer kanboard
  "feedback": { ... } // The multi-game feedback system
}

🎯 Tip: Always check source === “kanboard-unified” to validate file integrity before running deep merge operations.

2️⃣ Board Structure (root.board)

The primary kanboard uses a column-first relationship mapping combined with a normalized task dictionary.

• board.columns: Array of columns determining structure and WIP limits.
• board.columns[].taskIds: The exact ordered array of strings referencing tasks.
• board.tasks: An object map (Record<string, Task>) containing the actual task metadata.

Task Metadata Schema:

• id (string)
• title (string)
• description (string)
• tags (string[])
• assignee (string)
• priority (High | Medium | Low)
• estimate (number)
• color (string - hex)
• createdAt / dueDate (timestamps/strings)

3️⃣ Feedback Structure (root.feedback)

The feedback system nests items by their exact gameId directly mapping to the Nakama collections.

• feedback.totalGames & totalTickets: Helpful metric scalars.
• feedback.boards: Object map keyed by gameId (e.g., "bombergang": { ... }).
• feedback.boards[gameId].board.items: Array of feedback objects.

Feedback Item Schema:

• id (string - generated via prefix e.g., fb-1773491499934-389s)
• title (string)
• description (string)
• status (open | closed | resolved)
• category (Bug | Idea | UX | Visual | Balance)
• priority (High | Medium | Low)
• createdAt (timestamp number)

🧬 Data Fusion (SSOT) Rules

When importing this JSON, the engine applies specific Deep Merge logic:

1. Never Duplicate: Checks incoming items against existing items using exact id matching.
2. Preserve State: If a task or feedback item already exists, do not overwrite its current state (preventing loss of live progress).
3. Smart Append: Append missing taskIds to the Done or Backlog columns to avoid violating strict wipLimits in the active columns.
4. Reactivity: Svelte 5 $state arrays (e.g. feedbackItems) must trigger reassignment feedbackItems = [...newSet] to guarantee view updates.

🚀 Pro-Tips

• Emojis & Readability: Always render feedback categories with their respective icons/emojis (🐛 Bug, 🎨 Visual, ⚖️ Balance) in the UI.
• Inline Promotion: Feedback items are easily promoted to Kanboard tasks by porting their stringified properties into a new task-xxx object and inserting into board.tasks.
• Nakama Storage: The entire object should be stored as JSON objects in the global backend config collection to enable real-time multiplayer syncing of dev boards.