Flash-Code

A beautiful, interactive flashcard-based quiz system for learning web development concepts built with Next.js 14, TypeScript, Tailwind CSS, and Framer Motion.

🎯 Features

• Interactive Flashcards: 3D flip animation using CSS transforms and Framer Motion
• Glassmorphism Design: Modern dark-themed UI with frosted glass effects
• Single Player Mode: Learn at your own pace with category-based flashcards
• Multiplayer Battle Mode: Challenge friends in real-time quiz competitions
• Room-Based Multiplayer: Create rooms or join existing rooms with unique codes
• Live Leaderboard: Real-time score tracking and competitive rankings
• Category-Based Learning: Organize flashcards by topics (React, Next.js, TypeScript, Database)
• Progress Tracking: Real-time progress bar and score tracking
• Responsive Design: Works seamlessly on desktop, tablet, and mobile devices
• Smooth Animations: Framer Motion for elegant transitions and interactions
• API Integration: Fetch flashcard data from Next.js API routes
• Room Management: Create, join, and manage multiplayer game sessions

📁 Project Structure

flash-code/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── cards/
│   │   │   │   └── route.ts          # API endpoint returning flashcard data
│   │   │   └── rooms/
│   │   │       └── route.ts          # Multiplayer room management API
│   │   ├── layout.tsx                # Root layout with metadata
│   │   ├── page.tsx                  # Main application page with game mode selection
│   │   └── globals.css               # Global styles and animations
│   ├── components/
│   │   ├── FlashCard.tsx             # 3D flip card component
│   │   ├── ProgressBar.tsx           # Progress tracking component
│   │   ├── CategoryCard.tsx          # Category selection component
│   │   ├── MultiplayerLobby.tsx      # Multiplayer room creation and joining
│   │   └── MultiplayerGame.tsx       # Multiplayer game interface with leaderboard
│   └── lib/
│       ├── socket.ts                 # Socket.IO client initialization
│       ├── types.ts                  # TypeScript types for multiplayer features
│       └── eventEmitter.ts           # Event emitter utility for pub/sub
├── package.json                      # Dependencies and scripts
├── tsconfig.json                     # TypeScript configuration
├── next.config.mjs                   # Next.js configuration
├── tailwind.config.ts                # Tailwind CSS configuration
├── postcss.config.js                 # PostCSS configuration
├── eslint.config.js                  # ESLint configuration
└── .gitignore                        # Git ignore rules

🚀 Getting Started

Prerequisites

• Node.js 18+ (Latest LTS recommended)
• npm or yarn package manager

Installation

1. Clone or extract the project

cd flash-code

2. Install dependencies

npm install

3. Run the development server

npm run dev

4. Open in browser

Navigate to http://localhost:3000 to see your application in action.

📊 Project Architecture

Components

FlashCard.tsx

• Displays individual flashcards with question and answer
• 3D flip animation using Framer Motion
• Shows difficulty level and category
• Tracks when cards are interacted with

// Props
interface FlashCardProps {
  question: string;
  answer: string;
  category: string;
  difficulty: "easy" | "medium" | "hard";
  onFlip?: () => void;
}

ProgressBar.tsx

• Shows current progress through the flashcard set
• Animated width based on completion percentage
• Displays remaining cards count

// Props
interface ProgressBarProps {
  current: number;
  total: number;
}

CategoryCard.tsx

• Category selection card with icon
• Shows number of available cards per category
• Selection state indication
• Click to select for learning

// Props
interface CategoryCardProps {
  title: string;
  description: string;
  count?: number;
  isSelected?: boolean;
  onClick: () => void;
}

MultiplayerLobby.tsx

• Room creation interface with category selection
• Room joining with unique room codes
• Player name input
• Copy room code functionality for sharing

Features:

• Create a new multiplayer game room
• Join existing rooms with 8-character codes
• Display created room code for sharing
• Scale up to 4 players per room

MultiplayerGame.tsx

• Live multiplayer game interface
• Real-time player score tracking
• Live leaderboard showing all player scores and progress
• Answer tracking for each player
• Game completion with final rankings and accuracy calculations

Features:

• Displays all connected players with their scores
• Visual indicator for answered cards
• Final results screen with player rankings
• Rank indicator (1st, 2nd, 3rd place, etc.)
• Play again or exit options

API Routes

GET /api/cards

Returns an array of all flashcards. Supports filtering by category via query parameter.

GET /api/cards
GET /api/cards?category=React

Response:

[
  {
    "id": 1,
    "question": "What is JSX?",
    "answer": "JSX is a syntax extension for JavaScript...",
    "category": "React",
    "difficulty": "easy"
  }
]

POST /api/rooms

Manages multiplayer room operations with three actions:

Create Room:

POST /api/rooms
Content-Type: application/json

{
  "action": "CREATE",
  "category": "React",
  "maxPlayers": 4
}

Response:

{
  "success": true,
  "roomId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Join Room:

POST /api/rooms
Content-Type: application/json

{
  "action": "JOIN",
  "roomId": "a1b2c3d4...",
  "playerName": "John Doe"
}

Response:

{
  "success": true,
  "playerId": "player-1234567890"
}

Get Room Info:

POST /api/rooms
Content-Type: application/json

{
  "action": "GET_ROOM",
  "roomId": "a1b2c3d4..."
}

Response:

{
  "success": true,
  "room": {
    "id": "a1b2c3d4...",
    "name": "Room abc1d2e3",
    "category": "React",
    "players": [
      { "id": "player-1", "name": "Alice", "score": 5, "answered": true },
      { "id": "player-2", "name": "Bob", "score": 3, "answered": false }
    ],
    "maxPlayers": 4,
    "gameStatus": "IN_PROGRESS"
  }
}

Main Page (page.tsx)

Game Flow:

1. Game Mode Selection Screen:

   • Choose between Single Player or Multiplayer Battle
   • Single Player for solo learning
   • Multiplayer for competitive quizzes with friends

2. Single Player Mode:

   • Category Selection Screen
   • Learning Screen with individual progress tracking
   • Results Screen with accuracy and score

3. Multiplayer Mode:

   • Lobby Screen: Create or join a room
     • Create Room: Shows unique room code for sharing
     • Join Room: Enter 8-character room code
   • Game Screen: Live multiplayer gameplay
     • Real-time leaderboard with all players' scores
     • Live progress bar and card counter
     • Answer tracking for each player
   • Results Screen: Final rankings and player statistics

State Management:

• gameMode: Current game mode (menu, single, multiplayer-lobby, multiplayer-game)
• cards: Array of flashcard data
• currentIndex: Current card position
• selectedCategory: Currently selected learning category
• score: Player's score in current session
• answeredCards: Set of card IDs that have been interacted with
• showResults: Whether to display results screen
• multiplayerData: Room ID, player name, and category for multiplayer games

🎨 Design System

Colors

• Dark Theme: #1a1a2e, #16213e, #0f3460, #533483
• Glassmorphism: Frosted glass effect with blur and transparency
• Gradients: Blue to Purple accent gradients

Typography

• Headings: Bold, large sizes (2xl-5xl)
• Body Text: Regular weight with gray tones
• Accent Text: Blue/Purple for interactive elements

Animations

• Card Flip: 0.6s ease-in-out 3D rotation
• Progress Bar: Smooth width animation
• Button Hover: Scale 1.05 with smooth transition
• Card Entrance: Fade and slide up animation

🔧 Configuration Files

tailwind.config.ts

Extends Tailwind with custom colors, animations, and glassmorphism utilities.

next.config.mjs

React strict mode enabled for development safety.

tsconfig.json

Configured for strict type checking and path aliases (@/*).

📦 Dependencies

• next: ^14.0.0 - React framework
• react: ^18.2.0 - UI library
• typescript: ^5.3.0 - Type safety
• tailwindcss: ^3.4.0 - Utility-first CSS
• framer-motion: ^10.16.0 - Animation library
• lucide-react: ^0.263.0 - Icon library
• socket.io-client: ^4.7.2 - Real-time multiplayer communication (future upgrade)
• uuid: ^9.0.1 - Unique ID generation for rooms and players

🎯 Learning Outcomes

By building this project, you'll learn:

• ✅ Next.js 14 App Router and API Routes
• ✅ React Hooks (useState, useEffect)
• ✅ TypeScript interfaces and types
• ✅ Tailwind CSS utility-first styling
• ✅ CSS 3D transforms and animations
• ✅ Framer Motion for smooth interactions
• ✅ Component composition and props
• ✅ Data fetching in Next.js
• ✅ Multiplayer game architecture and lobbies
• ✅ Real-time state synchronization across players
• ✅ Room-based game management
• ✅ Competitive gameplay UI and leaderboards

🚀 Future Enhancements

• ✅ Multiplayer Mode (NOW AVAILABLE) - Create rooms and challenge friends
• Implement Socket.IO for real-time sync during gameplay
• Add persistent storage with database (MongoDB/PostgreSQL)
• Implement spaced repetition algorithm for optimal learning
• Add user authentication and persistent progress tracking
• Create user profiles with achievement badges
• Implement chat during multiplayer games
• Add difficulty-based matchmaking
• Create seasonal leaderboards
• Add custom flashcard creation and sharing
• Implement mobile app version with React Native
• Add voice chat during multiplayer battles

---

📚 Complete Documentation

Flash-Code includes comprehensive documentation for every use case. Start here:

👶 New to Flash-Code?

→ QUICKSTART.md - Get running in 2 minutes

🛠️ Setting Up

→ SETUP.md - Complete installation (10 min)

🎮 Playing Multiplayer

→ MULTIPLAYER.md - How to play with friends (10 min)

🗄️ Database Questions

→ DATABASE.md - Data storage & setup (20 min)

🚀 Ready to Deploy?

→ DEPLOYMENT.md - 4 hosting options (15 min)

🏗️ Want to Extend the Code?

→ ARCHITECTURE.md - Full technical guide (30 min)

❌ Something Broken?

→ TROUBLESHOOTING.md - 30+ solutions (browse as needed)

✅ Pre-Launch Checklist

→ CHECKLIST.md - Verify everything works (30 min)

📖 Browse All Docs

→ INDEX.md - Complete documentation map (by role or task)

---

🚀 Quick Setup

# 1. Install & setup database
./setup.sh                        # Mac/Linux
setup.bat                         # Windows
# OR manually:
npm install
npx create-db
npx prisma migrate deploy
npm run seed

# 2. Start development
npm run dev

# 3. Open browser
open http://localhost:3000

# 4. Test multiplayer (2 windows)
# Window 1: Create Room
# Window 2: Join same room

# 5. Deploy to Vercel
git push origin main
# Then visit vercel.com

See QUICKSTART.md for the 2-minute version.

---

💻 Tech Stack

Category	Technology
Frontend	React 18, Next.js 14, TypeScript
Styling	Tailwind CSS, CSS-in-JS
Animations	Framer Motion
Database	PostgreSQL, Prisma ORM
Real-Time	Socket.IO 4.7
Icons	Lucide React
Deployment	Vercel, Railway, AWS, Self-hosted

---

👥 For Different Roles

👨‍💻 Developers

• Read: ARCHITECTURE.md for component structure
• Start: npm run dev
• Database: npm run db:studio

📱 Product Managers

• Read: README.md for features
• Check: CHECKLIST.md for launch readiness
• Deploy: DEPLOYMENT.md

🚀 DevOps/Deployment

• Read: DEPLOYMENT.md for all platforms
• Setup: SETUP.md → Database section
• Monitor: Database dashboards

🔐 Security

• Read: DEPLOYMENT.md → Security section
• Review: ARCHITECTURE.md → Security patterns
• Verify: CHECKLIST.md → Security items

---

❓ Need Help?

1. Quick answers: Check TROUBLESHOOTING.md
2. How-to guides: Use QUICKSTART.md & SETUP.md
3. Code questions: See ARCHITECTURE.md
4. Deployment: Follow DEPLOYMENT.md
5. Browse all: INDEX.md maps docs by role

---

🎉 Ready to Launch?

1. ✅ Complete CHECKLIST.md
2. 📖 Follow DEPLOYMENT.md
3. 🚀 Deploy to Vercel
4. 🎮 Share with friends!

---

Need more info? Every guide is in the docs folder. Start with INDEX.md!

---

📝 License

MIT License - Feel free to use this project for learning and development.

---

Happy Learning! Build amazing web applications with Flash-Code! 🎓