deck-management

name	deck-management
description	How decks are stored in SQL, how to create/read/update/delete decks. Read before working with deck data.

Deck Management

Decks are stored in the decks SQL table via Drizzle ORM. Each deck row contains the full deck JSON (slides, metadata) in a data TEXT column.

Schema

CREATE TABLE decks (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  data TEXT NOT NULL,       -- Full deck JSON (slides array, metadata)
  created_at TEXT DEFAULT (current_timestamp),
  updated_at TEXT DEFAULT (current_timestamp)
);

Deck JSON Structure

The data column stores a JSON object:

{
  "title": "My Presentation",
  "slides": [
    {
      "id": "slide-1",
      "content": "<div class=\"fmd-slide\" style=\"...\">...</div>",
      "layout": "title"
    },
    {
      "id": "slide-2",
      "content": "<div class=\"fmd-slide\" style=\"...\">...</div>",
      "layout": "content"
    }
  ]
}

Each slide has an id, HTML content, and optional layout type.

Reading Decks

From scripts:

# List all decks (metadata only)
pnpm action list-decks

# Get a specific deck with all slides
pnpm action get-deck --id=<deckId>

# Get one slide's full HTML without loading the rest of the deck
pnpm action get-deck --id=<deckId> --slideId=<slideId> --compact=false

# See what the user is looking at
pnpm action view-screen

From actions:

• list-decks -- list all decks (returns id, title, slide count, timestamps)
• get-deck -- get a single deck; Slides chat calls are compact by default. Pass slideId for one targeted slide (full HTML by default), or use compact=false when a full deck read is actually needed

Writing Decks

From scripts:

# Use db-exec to insert/update
pnpm action db-exec --sql "INSERT INTO decks (id, title, data) VALUES (?, ?, ?)" --params '["new-id", "Title", "{...}"]'

From actions:

• add-deck -- create a new deck
• save-deck -- replace an authoritative full deck payload
• delete-deck -- delete a deck

Important Rules

1. Always use the API or Drizzle -- never write raw JSON files for deck storage
2. Deck IDs are stable -- once created, a deck's ID doesn't change
3. Slide IDs within a deck are stable -- used for referencing specific slides
4. The data column is the full source of truth -- title is duplicated at the top level for listing queries
5. SSE events (source: "resources") fire when decks change, keeping the UI in sync