🎴 DeckWiz 🧙‍♂️

Master any subject with intelligent spaced repetition

DeckWiz is a modern, clean flashcard application that helps you learn and retain information through adaptive spaced repetition. Built with cutting-edge web technologies, it provides a seamless learning experience that's completely free.

🌐 Production Deployment

It's live! Check it out at:

🪄 deckwiz.cyberalcove.com

Sign up for a free account and start mastering your flashcards today!

✨ Features

• 🧠 Spaced Repetition Algorithm - Smart learning system that adapts to your pace
• 📚 Custom Deck Management - Create and organize multiple flashcard decks
• 🔐 Secure Authentication - Email/password and GitHub OAuth support
• 📊 Progress Tracking - Monitor your learning statistics and achievements
• 🎨 Modern UI - Clean, responsive interface with dark mode support
• 📧 Email Verification - Secure account management with email workflows
• 🔒 Encrypted Database - Your data is protected with SQLite encryption

🛠️ Technology Stack

Frontend

• Astro - High-performance web framework
• Tailwind CSS - Utility-first CSS framework
• DaisyUI - Tailwind component library with retro and dim themes
• Astro Icon - Iconify integration with Font Awesome 6

Backend & Authentication

• Better Auth - Modern authentication library
• Email & Password - Traditional authentication with verification
• GitHub OAuth - Social authentication provider
• Google OAuth - Social authentication provider
• Password Reset - Secure password recovery flow
• Email Change - Verified email update workflow

Database

• SQLite - Lightweight, file-based database
• better-sqlite3-multiple-ciphers - Encrypted SQLite with cipher support

Email & Notifications

• AWS SES - Amazon Simple Email Service integration
• Resend - Modern email API alternative

Development Tools

• TypeScript - Type-safe JavaScript
• ESLint - Code linting and quality
• Prettier - Code formatting
• Docker - Containerization for deployment
• Docker Compose - Multi-container orchestration

📁 Project Structure

/
├── src/
│   ├── pages/              # Astro pages (file-based routing)
│   │   ├── index.astro     # Landing page
│   │   ├── login.astro     # Authentication
│   │   ├── signup.astro    # Registration
│   │   ├── dashboard.astro # Main app interface
│   │   ├── study/          # Study session pages
│   │   ├── configure/      # Deck configuration
│   │   └── api/            # API endpoints
│   │       └── auth/       # Better Auth API routes
│   ├── components/         # Reusable Astro components
│   │   ├── FlashCard.astro
│   │   ├── DeckTable.astro
│   │   ├── ConfigTable.astro
│   │   └── ...
│   ├── layouts/            # Page layouts
│   │   ├── Layout.astro    # Main layout wrapper
│   │   ├── Header.astro
│   │   └── Footer.astro
│   ├── actions/            # Server actions
│   ├── auth-client.ts      # Client-side auth utilities
│   ├── middleware.ts       # Astro middleware
│   └── main.css            # Global styles
├── db/                     # Database directory
│   └── db_connection.ts    # SQLite connection
├── db_migration/           # Database migration scripts
├── better-auth_migrations/ # Better Auth schema migrations
├── auth.ts                 # Server-side auth configuration
├── email.ts                # Email service configuration
├── astro.config.mjs        # Astro configuration
├── tailwind.config.mjs     # Tailwind CSS configuration
├── Dockerfile              # Production container
├── compose.yml             # Production deployment
└── package.json

🚀 Getting Started

Prerequisites

• Node.js
• npm
• Docker (for containerized deployment)

Installation

1. Clone the repository

   git clone https://github.com/hel-b/astro-flash.git
   cd astro-flash

2. Install dependencies

   npm install

3. Set up environment variables

   Create a .env file in the root directory:

   # Database
   DB_FILE_PATH=/app/db/app.db
   DB_ENCRYPT_KEY=your-encryption-key-here
   
   # Better Auth
   BETTER_AUTH_SECRET=your-auth-secret-here
   BETTER_AUTH_URL=http://localhost:4327 # Adjust for production
   
   # GitHub OAuth (optional)
   GITHUB_CLIENT_ID=your-github-client-id
   GITHUB_CLIENT_SECRET=your-github-client-secret
   
   # Google OAuth (optional)
   GOOGLE_CLIENT_ID=your-google-client-id
   GOOGLE_CLIENT_SECRET=your-google-client-secret
   
   # Email Configuration
   NOREPLY_EMAIL=[email protected]
   ADMIN_EMAIL=[email protected]
   
   # AWS SES (if using AWS)
   AWS_REGION=us-west-1 # Adjust as needed
   AWS_ACCESS_KEY_ID=your-access-key
   AWS_SECRET_ACCESS_KEY=your-secret-key
   
   # Resend (if using Resend)
   RESEND_API_KEY=your-resend-api-key

4. Create the database

    # Step 1: Run Better Auth migrations
    npx @better-auth/cli@latest migrate
    # Step 2: Migrate application tables
    node ./db_migration/migrate-tables.js
    # OR copy fresh pre-seeded database
    cp ./db/app-fresh.db ./db/app.db

5. Start the development server

   npm start

   The application will be available at http://localhost:4327

🧞 Commands

All commands are run from the root of the project:

Command	Action
npm install	Install dependencies
npm start	Start dev server at localhost:4327
npm run build	Build production site to ./dist/
npm run preview	Preview build locally before deploying
npm run lint	Run ESLint on source files
npm run astro	Run Astro CLI commands

🐳 Docker Deployment

Repo contains a base Dockerfile ready for production deployment.

🔒 Security Features

• Encrypted SQLite Database - All data encrypted at rest
• Email Verification - Required for new accounts
• Password Reset Flow - Secure token-based reset with expiration
• HTTPS Ready - Let's Encrypt SSL support via Docker labels
• Environment Isolation - Secrets managed via environment variables
• OAuth Integration - Secure third-party authentication

🎨 Theming

DeckWiz includes two beautiful themes powered by DaisyUI:

• Retro - Light mode with vintage aesthetics
• Dim - Dark mode for comfortable night-time studying

Users can toggle between themes using the theme controller component.

📊 Learning Algorithm

DeckWiz implements a modified version of the SM-2 (SuperMemo 2) algorithm, a proven spaced repetition system that optimizes long-term memory retention.

How It Works

The algorithm tracks three key metrics for each flashcard:

• Streak (n) - Number of consecutive correct responses
• Easiness Factor (EF) - Difficulty multiplier (minimum 1.3)
• Interval (I) - Days until next review

Scheduling Logic

• First correct answer: Review again in 1 day
• Second correct answer: Review again in 6 days
• Subsequent correct answers: Interval multiplied by the Easiness Factor
• Incorrect answer: Reset streak and interval to 0

The Easiness Factor adjusts based on your performance, making difficult cards appear more frequently while easy cards have longer intervals between reviews.

Current Implementation

Our implementation (sm2Alg in src/helpers.ts) adapts the SM-2 algorithm with a binary pass/fail system instead of the original 0-5 quality rating scale.

Algorithm Details

Input Parameters:

• pass (boolean) - Whether the card was answered correctly
• streak (number) - Current consecutive correct answers
• EF (number) - Easiness Factor for the card
• interval (number) - Current interval in days

Output:

• Updated streak, EF, and interval values

Current Implementation (TypeScript):

/**
 * SM-2 Spaced Repetition Algorithm (Modified for DeckWiz)
 * @param params - Algorithm input
 * @param params.pass - Whether the card was answered correctly
 * @param params.streak - Current consecutive correct answers
 * @param params.EF - Easiness Factor for the card
 * @param params.interval - Current interval in days
 * @returns Updated streak, EF, and interval values
 */
export const sm2Alg = ({
  pass,
  streak,
  EF,
  interval,
}: {
  pass: boolean
  streak: number
  EF: number
  interval: number
}): { streak: number; EF: number; interval: number } => {
  if (pass) {
    if (streak === 0) {
      interval = 1 // First correct: review in 1 day
    } else if (streak === 1) {
      interval = 6 // Second correct: review in 6 days
    } else {
      interval = Math.round(interval * EF) // Subsequent: multiply by EF
    }
    streak += 1
  } else {
    streak = 0 // Reset streak on failure
    interval = 0 // Review again immediately
  }
  // Adjust Easiness Factor
  EF +=
    0.1 - 4.2 * (1 - Number(pass)) * (0.08 + 4.2 * (1 - Number(pass)) * 0.02)
  if (EF < 1.3) {
    EF = 1.3 // Minimum EF
  }
  return { streak, EF, interval }
}

The EF formula is adapted from the original SM-2 quality-based calculation:

• Correct answer (pass=true): EF increases by 0.1, making future intervals longer
• Incorrect answer (pass=false): EF decreases by ~0.8, making future intervals shorter

This simplified binary approach makes reviews faster while preserving the core benefits of spaced repetition—cards you struggle with appear more frequently, while mastered cards are shown less often.

Reference

Based on the SuperMemo SM-2 algorithm developed by Piotr Woźniak. Learn more:

• SuperMemo Algorithm Description
• SM-2 Algorithm on Wikipedia

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🔗 Links

• Live Site: deckwiz.cyberalcove.com
• Astro Documentation: Astro Docs
• Report Issues: GitHub Issues

---

Built with ❤️ using Astro, Tailwind CSS, and Better Auth