A modern flashcard application built with React and Node.js, designed as a foundation for learning AI-assisted development with Claude Code.

This is a starter repository for the AI Capstone course. Students will use this codebase to learn:

• How to integrate Claude Code into VS Code
• Using AI to understand unfamiliar codebases
• Adding features with AI assistance (spaced repetition algorithm)
• Following best practices for Git workflows and testing

• Deck Management: Create, view, and organize flashcard decks
• Card Display: Clean flashcard interface with flip animation
• Basic Review System: Study cards and submit ratings
• Statistics Dashboard: Track progress with deck statistics
• Responsive UI: Built with React and Tailwind CSS

The following features are intentionally left incomplete for students to implement:

1. Spaced Repetition Algorithm (SM-2)

   • Currently, cards are not intelligently scheduled
   • Students will implement the SM-2 algorithm in the review endpoint

2. Advanced Statistics

   • Current stats are basic placeholders
   • Students will add: cards due today, mastered cards, retention rates

3. Comprehensive Tests

   • Basic test structure is in place
   • Students will add unit and integration tests

Frontend:

• React 18 with TypeScript
• Vite for build tooling
• TailwindCSS for styling
• React Router for navigation

Backend:

• Node.js with Express
• TypeScript
• Prisma ORM with SQLite
• RESTful API design

Development:

• Vitest for testing
• ESLint for linting
• GitHub Actions for CI

• Node.js 20+ and npm
• Git

1. Clone the repository:

git clone <your-repo-url>
cd flashcards

2. Install dependencies:

npm install

3. Configure environment variables:

cd backend
cp .env.example .env
cd ..

The .env.example file includes the following variables:

• DATABASE_URL: Path to the SQLite database file (default: file:./dev.db)
• PORT: Backend server port (default: 3001)
• NODE_ENV: Environment mode (default: development)

You can modify these values in your .env file if needed.

4. Set up the database:

cd backend
npm run db:push
npm run db:seed
cd ..

5. Start the development servers:

npm run dev

This will start:

• Backend API on http://localhost:3001
• Frontend on http://localhost:5173

The app uses npm workspaces. You can run commands in specific workspaces:

# Run backend commands
npm run dev --workspace=backend
npm run test --workspace=backend

# Run frontend commands
npm run dev --workspace=frontend
npm run test --workspace=frontend

# Or use the root scripts
npm run dev        # Runs both frontend and backend
npm test           # Runs all tests
npm run lint       # Lints all code

flashcards/
├── backend/
│   ├── prisma/
│   │   └── schema.prisma      # Database schema
│   ├── src/
│   │   ├── routes/            # API endpoints
│   │   ├── db.ts              # Prisma client
│   │   ├── seed.ts            # Sample data
│   │   └── index.ts           # Express server
│   └── tests/                 # Backend tests
├── frontend/
│   ├── src/
│   │   ├── components/        # React components
│   │   ├── pages/             # Page components
│   │   ├── lib/               # API client & types
│   │   └── App.tsx            # Main app component
│   └── public/                # Static assets
└── package.json               # Workspace configuration

• GET /api/decks - List all decks
• GET /api/decks/:id - Get deck details
• POST /api/decks - Create a deck
• PUT /api/decks/:id - Update a deck
• DELETE /api/decks/:id - Delete a deck

• GET /api/decks/:deckId/cards - Get cards in a deck
• GET /api/decks/:deckId/due - Get due cards (stub for spaced repetition)
• POST /api/cards - Create a card
• PUT /api/cards/:id - Update a card
• DELETE /api/cards/:id - Delete a card

• POST /api/reviews - Submit a review (stub for SM-2 algorithm)
• GET /api/reviews/card/:cardId - Get review history

• GET /api/stats/:deckId - Get deck statistics

The app uses Prisma with SQLite. Key models:

• Deck: Flashcard collections
• Card: Individual flashcards with question/answer
• Review: Review history with spaced repetition data
• StudySession: Study session tracking

See backend/prisma/schema.prisma for full schema.

Use Claude Code to explore:

1. Ask: "Explain how the card delivery system works in this app"
2. Ask: "Show me where I would add the spaced repetition algorithm"
3. Ask: "What database changes are needed to track review history?"

With Claude Code's help, implement:

1. SM-2 Algorithm: Update backend/src/routes/reviews.ts

   • Calculate ease factor, interval, and next review date
   • Update the Review model with proper values

2. Due Cards Filter: Update backend/src/routes/decks.ts

   • Filter cards by nextReviewDate <= today

3. Enhanced Statistics: Update backend/src/routes/stats.ts

   • Calculate cards due today
   • Calculate mastered cards (high ease factor)

4. Testing: Add tests in backend/tests/

   • Test SM-2 calculations
   • Test API endpoints

1. Create a new branch for your work:

git checkout -b feature/spaced-repetition

2. Commit your changes with descriptive messages:

git add .
git commit -m "Implement SM-2 spaced repetition algorithm"

3. Push and create a pull request:

git push origin feature/spaced-repetition

Run all tests:

npm test

Run tests with coverage:

npm test -- --coverage

Check code style:

npm run lint

npm run build

This builds both frontend and backend into their respective dist/ directories.

The project includes a GitHub Actions workflow that:

• Runs linting
• Runs tests
• Builds the project

The workflow runs on pushes to main and on pull requests.

Ideas for future lessons:

• LLM-Generated Cards: Use OpenAI/Anthropic APIs to generate flashcards from text
• PDF Import: Parse lecture slides and create cards automatically
• Interactive Cards: Add code snippets, images, or algorithm visualizations
• Freeform Answers: Use LLMs to evaluate open-ended responses
• Agent Frameworks: Integrate DSPy, LangChain, or Kani

• SM-2 Algorithm Explanation
• Prisma Documentation
• React Documentation
• Claude Code Documentation

Backend won't start:

• Make sure you ran npm run db:push in the backend directory
• Check that port 3001 is available

Frontend can't connect to backend:

• Ensure backend is running on port 3001
• Check the proxy configuration in frontend/vite.config.ts

Database is empty:

• Run npm run db:seed in the backend directory

TypeScript errors:

• Run npm install to ensure all dependencies are installed
• Try restarting your editor

MIT

This is an educational project. Students should work on their own branches and submit pull requests for review.