flashcard-engine

# flashcard-engine

Spaced repetition flashcard system with SM-2 scheduling. Cards support Markdown. Import from Anki or CSV.

## When to use

- Studying card decks with spaced repetition scheduling
- Creating or editing flashcard decks and cards
- Importing Anki .apkg decks or CSV card files
- Checking the review schedule for upcoming due cards
- Exporting decks to CSV or JSON

## Prerequisites

- Node.js 20+
- Server running locally (default port 4000)

## Quick Start

```bash
pnpm install
pnpm dev
# Server: http://localhost:4000
# Client: http://localhost:5173
```

## Study Flow

1. Open the dashboard at http://localhost:5173
2. Click a deck that has due cards (red badge)
3. Read the card front
4. Press Space or click "Show answer"
5. Read the answer
6. Grade 0-5 (or press 0-5 on keyboard):
   - 0 = Again (forgot completely)
   - 1 = Hard
   - 2 = Difficult
   - 3 = Good
   - 4 = Easy
   - 5 = Perfect (instant recall)
7. Repeat until no more due cards

## API Reference

### Study

```
GET  /api/decks/:id/study        Next due card for this deck
POST /api/cards/:id/review       Grade a card

Body: { "grade": 4 }
Response: { "nextReview": "2024-04-01", "interval": 8 }
```

### Decks

```
GET    /api/decks             List all decks with due counts
POST   /api/decks             Create deck { name, description }
GET    /api/decks/:id         Deck with full stats
PATCH  /api/decks/:id         Update deck { name?, description? }
DELETE /api/decks/:id         Delete deck and all cards
```

### Cards

```
GET    /api/decks/:id/cards   List cards in deck
POST   /api/decks/:id/cards   Create card { front, back, tags? }
PATCH  /api/cards/:id         Update card { front?, back?, tags? }
DELETE /api/cards/:id         Delete card
```

### Import

```
POST /api/import/csv          Upload CSV file (multipart/form-data, field: file)
POST /api/import/anki         Upload .apkg file (multipart/form-data, field: file)
```

### Export

```
GET /api/decks/:id/export/csv    Download deck as CSV
GET /api/decks/:id/export/json   Download deck as JSON
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `4000` | Server port |
| `DATA_DIR` | `~/.flashcard-engine` | SQLite storage directory |
| `CORS_ORIGIN` | `http://localhost:5173` | Allowed CORS origin |
| `LOG_LEVEL` | `info` | Log level: debug, info, warn, error |

## SM-2 Grades

| Grade | Label | Meaning |
|---|---|---|
| 0 | Again | Complete blackout |
| 1 | Hard | Remembered with significant difficulty |
| 2 | Difficult | Remembered with effort |
| 3 | Good | Correct with some hesitation |
| 4 | Easy | Correct after brief thought |
| 5 | Perfect | Instant recall |

Grades 0-2 reset the card's interval. Grades 3-5 increase the interval using the SM-2 formula.

## Troubleshooting

### No cards are due

All cards have been reviewed. Check the Schedule page for upcoming due dates.

### Import fails for Anki .apkg

The .apkg must be from Anki 2.x. Verify the file is not corrupted. Very large decks (10,000+ cards) may take up to 30 seconds to import.

### Deck shows 0 due but I have unreviewed cards

New cards are separate from due cards. Configure "New cards per day" in Settings to introduce new cards alongside reviews.