Skip to content

How Cards Work

Jump to bottom
MightyXdash edited this page May 15, 2026 · 1 revision

How Cards Work

Cards are the core study unit in ONCard. Almost every major feature eventually reads from or writes to the card store.

You may refer to:

What a card contains

Every card has a small core set of fields:

  • id
  • question
  • title
  • subject
  • category
  • subtopic
  • hints
  • search_terms
  • answer
  • natural_difficulty
  • run_id
  • created_at
  • updated_at

There are also extra fields that may exist on some cards, such as:

  • mcq_answers
  • temporary-study metadata
  • feature-specific fields added by newer systems

The important idea is that ONCard keeps a stable card core, then stores extra feature data on top of it when needed.

How cards are stored

Cards are stored in ONCard's local SQLite database.

The cards table stores the main searchable fields directly:

  • title
  • question
  • answer
  • subject path
  • difficulty
  • timestamps

Structured lists such as hints and search terms are stored as JSON.

Extra card data is stored in extra_json. That is how ONCard can keep optional fields like mcq_answers without changing the core card shape every time a feature expands.

How cards are created

Cards can come from several places:

Manual or one-input creation

The user writes a question or topic, then autofill generates the rest of the card.

Files To Cards

FTC first generates raw study questions from files, then each question goes through the same autofill pipeline and becomes a normal saved card.

MCQ backfill

If a card is missing MCQ choices, ONCard can generate them later and save them back onto the card.

So even though cards may enter the system in different ways, they are normalized into the same storage model.

How cards are organized

Every card lives in a three-level subject path:

  • subject
  • category
  • subtopic

Examples:

  • Science -> Biology -> Plants
  • Mathematics -> Algebra -> Linear Equations
  • Computer Science / IT -> Programming -> Python / C++ / Java

If a value is missing, ONCard falls back to safe defaults like Mathematics, All, or All.

This subject path is used all over the app:

  • filtering
  • sidebar browsing
  • study sessions
  • stats
  • recommendation and weakness grouping

How answers and MCQs relate

The card's answer field is the main expected answer for grading and review.

If a card also has mcq_answers, ONCard treats:

  • mcq_answers[0] as the correct MCQ answer
  • the other 3 entries as distractors

When ONCard builds an MCQ payload, it shuffles the displayed choices, but the stored correct answer still comes from the first normalized item.

If a card is missing a normal answer but has valid MCQ answers, ONCard can use the correct MCQ answer as the effective expected answer.

That is why MCQ generation is not a separate card type. It is an extra layer attached to a normal card.

How study history connects to cards

Cards and attempts are stored separately.

The card record stores the study material itself. The attempts table stores what happened when a user studied that card:

  • answer text
  • marks
  • hidden analytics score
  • hints used
  • timestamps
  • correct or wrong state
  • optional MCQ data

This separation matters because one card can have many study attempts over time.

How card search works

ONCard supports full-text search over:

  • title
  • question
  • answer
  • search terms

If SQLite FTS5 is available, ONCard uses a virtual full-text index for faster searches. If not, it falls back to a simpler in-memory text search.

The search_terms field is intentionally capped at 5 items, so each card keeps a tight keyword summary instead of a noisy tag dump.

ONCard — Elevate your learning experience with offline AI.

Built for local AI usage • Enhance your learning experience
Licensed under Apache 2.0.

Setup Guide Performance Accounts AI Models Wikipedia search How FTC Works How Cards Work How MCQ Marking Works

Clone this wiki locally