Flashcard Backend API

A production-ready multi-user flashcard system with spaced repetition using the SM-2 algorithm.

Features

• ✅ User authentication (JWT-based)
• ✅ Create and manage flashcard decks
• ✅ Create and manage flashcards
• ✅ SM-2 spaced repetition algorithm
• ✅ Study sessions with intelligent scheduling
• ✅ Progress tracking and statistics
• ✅ RESTful API design
• ✅ TypeScript for type safety
• ✅ SQLite database (easy to migrate to PostgreSQL)

Tech Stack

• Runtime: Node.js 18+
• Language: TypeScript
• Framework: Express.js
• Database: SQLite (via Prisma ORM)
• Auth: JWT + bcrypt
• Validation: Zod

Quick Start

1. Install Dependencies

npm install

2. Set Up Environment

cp .env.example .env

Edit .env and set your JWT_SECRET:

DATABASE_URL="file:./dev.db"
JWT_SECRET="your-super-secret-jwt-key-at-least-32-characters-long"
JWT_EXPIRES_IN="7d"
PORT=3000
NODE_ENV="development"

3. Initialize Database

npx prisma generate
npx prisma migrate dev --name init

4. Start Development Server

npm run dev

The API will be running at http://localhost:3000

API Endpoints

Authentication

Register

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "username": "john_doe",
  "password": "secure_password123"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secure_password123"
}

Response:

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "john_doe"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Get Current User

GET /api/auth/me
Authorization: Bearer <token>

Decks

List Decks

GET /api/decks
Authorization: Bearer <token>

Create Deck

POST /api/decks
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Spanish Vocabulary",
  "description": "Common Spanish words and phrases"
}

Get Deck

GET /api/decks/:deckId
Authorization: Bearer <token>

Update Deck

PATCH /api/decks/:deckId
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Deck Name"
}

Delete Deck

DELETE /api/decks/:deckId
Authorization: Bearer <token>

Cards

List Cards in Deck

GET /api/cards/deck/:deckId
Authorization: Bearer <token>

Create Card

POST /api/cards
Authorization: Bearer <token>
Content-Type: application/json

{
  "deckId": "deck-uuid",
  "front": "Hola",
  "back": "Hello"
}

Get Card

GET /api/cards/:cardId
Authorization: Bearer <token>

Update Card

PATCH /api/cards/:cardId
Authorization: Bearer <token>
Content-Type: application/json

{
  "front": "Updated front",
  "back": "Updated back"
}

Delete Card

DELETE /api/cards/:cardId
Authorization: Bearer <token>

Study

Get Due Cards for Deck

GET /api/study/deck/:deckId/due
Authorization: Bearer <token>

Response:

{
  "card": {
    "id": "uuid",
    "front": "Hola",
    "back": "Hello",
    "dueDate": "2024-01-15T10:00:00Z",
    "easeFactor": 2.5,
    "interval": 0,
    "repetitions": 0
  }
}

Get All Due Cards

GET /api/study/due
Authorization: Bearer <token>

Submit Answer

POST /api/study/answer
Authorization: Bearer <token>
Content-Type: application/json

{
  "cardId": "card-uuid",
  "quality": 4
}

Quality Scale (SM-2):

• 5 - Perfect response
• 4 - Correct response after hesitation
• 3 - Correct response with difficulty
• 2 - Incorrect; correct answer seemed easy to recall
• 1 - Incorrect; correct answer remembered
• 0 - Complete blackout

Get Study Statistics

GET /api/study/stats
Authorization: Bearer <token>

Response:

{
  "totalCards": 150,
  "dueCards": 12,
  "reviewsToday": 25,
  "totalDecks": 5
}

Database Schema

User {
  id, email, username, password
  decks[]
  reviews[]
}

Deck {
  id, name, description
  userId
  cards[]
}

Card {
  id, front, back
  deckId
  easeFactor, interval, repetitions, dueDate
  reviews[]
}

Review {
  id, cardId, userId, quality, createdAt
}

SM-2 Algorithm

The system uses the SuperMemo SM-2 spaced repetition algorithm:

1. Quality < 3: Card is reset (review again tomorrow)
2. Quality ≥ 3: Card progresses through intervals:
   • First review: 1 day
   • Second review: 6 days
   • Subsequent: interval × easeFactor

The ease factor adjusts based on how difficult you find each card.

Development

Run in Development Mode

npm run dev

Build for Production

npm run build
npm start

Database Management

# Open Prisma Studio (GUI)
npm run prisma:studio

# Create migration
npx prisma migrate dev --name your_migration_name

# Reset database
npx prisma migrate reset

Testing

npm test

Project Structure

flashcard-backend/
├── prisma/
│   └── schema.prisma          # Database schema
├── src/
│   ├── algorithms/
│   │   └── sm2.ts             # SM-2 spaced repetition
│   ├── config/
│   │   ├── database.ts        # Prisma client
│   │   └── env.ts             # Environment validation
│   ├── middleware/
│   │   └── auth.middleware.ts # JWT authentication
│   ├── routes/
│   │   ├── auth.routes.ts     # Auth endpoints
│   │   ├── decks.routes.ts    # Deck management
│   │   ├── cards.routes.ts    # Card management
│   │   └── study.routes.ts    # Study sessions
│   ├── utils/
│   │   └── auth.ts            # Auth helpers
│   └── index.ts               # App entry point
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

Deployment

Environment Variables for Production

DATABASE_URL="file:./prod.db"  # Or PostgreSQL connection string
JWT_SECRET="very-long-secure-random-string"
JWT_EXPIRES_IN="7d"
PORT=3000
NODE_ENV="production"

Migrating to PostgreSQL

1. Update prisma/schema.prisma:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

2. Update .env:

DATABASE_URL="postgresql://user:password@localhost:5432/flashcards"

3. Run migrations:

npx prisma migrate dev

Future Enhancements

• Image/audio support for cards
• Deck sharing and public decks
• Export/import decks (.csv, .json)
• Mobile apps (React Native)
• Gamification (streaks, achievements)
• FSRS algorithm option (newer than SM-2)
• Cloze deletion cards
• Tag system for cards

License

MIT