ADR 0003: CSV Deck Import
Status
Accepted
Context
Users need to add custom flashcard decks. The device has no keyboard, so in-app card creation is impractical. We need a simple way to bulk-import cards from a computer.
Options considered:
| Format | Pros | Cons |
|---|---|---|
| CSV | Universal, editable in any spreadsheet, simple | No metadata, flat structure |
| JSON | Matches internal format, supports metadata | Harder to edit manually |
| Anki .apkg | Direct Anki compatibility | Complex format, needs parser |
| TSV | Like CSV, no comma escaping issues | Less universal |
| Markdown tables | Human-readable | Harder to parse reliably |
Decision
Support CSV as primary, JSON as secondary.
Consequences
Positive
- CSV is editable in Excel, Google Sheets, Numbers, Vim, anything
- One file per deck keeps things organized
- Simple format:
front,back— no learning curve - Comments (
#) and empty lines are ignored for flexibility - Duplicate detection prevents accidental re-imports
Negative
- No support for card metadata (tags, images, audio)
- Commas in card text need careful escaping (we split on first comma)
- No deck hierarchy or subdecks
- Can’t import Anki decks directly
Format
# Lines starting with # are comments
Hello,こんにちは
Thank you,ありがとう
Good morning,おはよう
Rules:
- Filename = deck name (e.g.,
Japanese.csv→ deck “Japanese”) - One card per line:
front,back - First comma splits front from back (rest of line is back)
- UTF-8 encoding required for non-Latin characters
Future work
- Anki
.apkgimport (popular request, complex to implement) .tsvsupport (trivial addition if requested)- In-app card editor (for small corrections, not bulk creation)