Skip to main content
A Deck is a named collection of Flashcard objects. Decks are the primary unit of persistence — saved to decks.json on the desktop and synced to Google Drive and mobile via Smart Merge.

​
Fields

​
deck_id
string
required
Unique identifier for this deck. Auto-generated as a UUID v4 on creation.
​
name
string
required
Display name shown in the deck list UI.
​
cards
Flashcard[]
default:"[]"
Ordered list of Flashcard objects belonging to this deck.
​
created_at
string
required
ISO 8601 timestamp of when the deck was first created, e.g. "2024-03-15T10:30:00.123456".
​
updated_at
string
required
ISO 8601 timestamp of the last modification. The Smart Merge sync algorithm uses this field to resolve conflicts — the deck with the newer updated_at wins.
​
source_folder
string
default:""
Filesystem path to the image folder that was scanned to generate this deck’s cards. Empty string for manually created decks.
​
description
string
default:""
Optional free-form description of the deck’s subject matter.

​
Properties

​
card_count → int

Computed property. Returns the number of cards currently in cards. Equivalent to len(deck.cards).

​
Methods

​
to_dict() → dict

Serializes the deck and all nested cards to a JSON-serializable dictionary. Each card in cards is serialized via Flashcard.to_dict().
​
deck_id
string
required
UUID string.
​
name
string
required
Display name.
​
created_at
string
required
ISO 8601 creation timestamp.
​
updated_at
string
required
ISO 8601 last-modified timestamp.
​
source_folder
string
required
Source image folder path (may be empty string).
​
description
string
required
Deck description (may be empty string).
​
cards
object[]
required
Array of serialized Flashcard objects.

​
from_dict(data) → Deck

Deserializes a Deck from a dictionary. Also deserializes all nested card objects by calling Flashcard.from_dict() on each entry in cards. Missing fields fall back to defaults (a new UUID is generated for deck_id if absent; timestamps default to now).

​
JSON example

{
  "deck_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "European Capitals",
  "created_at": "2024-03-15T10:30:00.123456",
  "updated_at": "2024-03-15T14:22:11.654321",
  "source_folder": "/Users/alex/scans/geography",
  "description": "Flashcards generated from geography lecture slides.",
  "cards": [
    {
      "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "question": "What is the capital of France?",
      "options": [
        "A. London",
        "B. Paris",
        "C. Berlin",
        "D. Madrid"
      ],
      "correct_answers": ["B"],
      "question_type": "single_choice",
      "image_path": "/Users/alex/scans/geography/slide_03.png",
      "notes": "",
      "status": 2
    }
  ]
}
The updated_at field is updated by the application whenever a card is added, edited, or removed. Always preserve its value when round-tripping JSON — overwriting it with an older timestamp will cause Smart Merge to discard newer changes on the next sync.

​
See also

Flashcard

The individual card data model stored inside a deck.

QuizSession

Tracks quiz progress over a deck’s cards.

Build docs developers (and LLMs) love

Get started for freeTalk to us