Managing decks and cards

Generating a deck from an article is the way in. This page is everything after that: writing cards by hand, editing them, sharing, and the bin.

/flashcards. An educator sees four tabs a learner does not — My Decks, Shared, Browse Cards, Trash — plus + New deck. A learner sees the decks and today's run, and nothing to choose between.

Who may do what

Three different questions, three different answers:

Question	Function	Answer
May I start a deck?	may_start_a_deck	Moderator or admin only. A deck grant is permission to look after the decks it names, not to add another to the tree filed wherever you like.
May I change this deck and write cards into it?	can_edit_deck	A moderator; the deck's owner (deck.user_id); or anybody whose grants cover it.
May a learner study it?	is_shared	Binary and site-wide. There is no per-learner deck ACL.

A deck grant names one deck, or one category branch of decks — and the branch is evaluated against the tree when it is asked, not frozen when it was written, so a deck filed under Cardiology tomorrow is covered by the grant given today. Grants are written at /flashcards/grants, moderator-only. See Grants.

Deleting and sharing are not moderator-only, whatever the docstrings say

DELETE /flashcards/{deck_id}, POST /{deck_id}/restore and PUT /{deck_id}/share all go through can_edit_deck. A deck-grant holder can delete and share a deck they hold, even though they cannot create one.

And GET /flashcards/trash returns an empty list to anybody who is not a moderator — so a grant holder who deletes a deck cannot see the bin to restore it. Ask a moderator.

Only DELETE /flashcards/{deck_id}/share — force-unshare — is admin-only.

A deck by hand

POST /flashcards/manual. The escape hatch, not the way in: cards belong to an article somebody has written, edited and published, and ai-cards is the path that makes them.

It asks for a title and a category, and the category is required here unlike almost everywhere else — a deck made by hand has no article to inherit one from, and a deck with no category cannot be found by anybody browsing the tree.

It starts unshared, like every new deck. Sharing is a second, deliberate act.

There is no deck from a PDF section. Cards are written from an article rather than from whatever happened to be on pages 40–58 of a source document.

Writing cards

POST /flashcards/decks/{deck_id}/cards, with a card_type from the five types.

One card written is not always one row stored. A cloze with three deletions is three cards over one passage; a reversed card is a pair. The count comes back from the server rather than being assumed to be one.

Type	What the form asks for
basic	Front and back
reversed	Front and back — stored as two independently scheduled rows
cloze	The passage with {{c1::answer::hint}}; the back is an optional note under the reveal
image	A picture, and what is being asked about it. An image card needs a picture or it is refused.
type_in	The answer, with alternatives separated by a vertical bar

A picture defaults to the answer side for every type except image, where it is the question whatever the box says.

Card pictures come from the image library through the picker, the same way a question's figures do.

Editing and deleting a card

Edit front and back in place. Delete asks first and is final: a card is not kept in a bin the way a deck is.

Deleting half of a reversed pair deletes both — half a pair is a card whose mirror asks a question nobody can now edit.

Linking a card

A card can be linked to a question or to an article (optionally a section). This is what lets a lab value or an article page show the cards that cover it.

A known gap

The four card-linking endpoints gate on is_moderator directly rather than going through can_edit_deck, so a non-moderator deck-grant holder is refused there even on a deck they can otherwise edit fully. The rest of flashcards.py honours grants correctly. See Grants.

Sharing

is_shared is the only switch that decides whether learners can study a deck, and it is site-wide once flipped. A generated deck starts unshared so an educator reads it before anybody studies it.

The bin

Deleting a deck is soft: deleted_at is set and it moves to the Trash tab, where it can be restored. ?permanent=true removes it for good.

The trash tab lists every binned deck for a moderator, and nothing for anybody else.

Staleness

The deck service compares a deck against the updated_at of every article linked to it, so a deck whose reading has moved on since the cards were written can say so. A deck links to every article its cards came from; exactly one of those links is flagged as the source. See Decks from an article.