# QuickPoll Next.js 15 Demo Project

A complete, step-by-step Next.js 15 polling application built for live-coding classroom demonstrations. Includes git tags at each development step for easy navigation during teaching.

## 📦 What's Included

### Zip Files (Individual Steps)
- `stap-0.zip` - Project setup + types + data
- `stap-1.zip` - Layout & Navigation
- `stap-2.zip` - Homepage with poll cards
- `stap-3.zip` - API routes (GET, POST)
- `stap-4.zip` - Vote API + demo form ⭐
- `stap-5.zip` - Poll detail page
- `stap-6.zip` - VoteForm component
- `stap-7.zip` - Error handling & loading states
- `stap-8.zip` - Middleware
- `bonus.zip` - Create poll page

### Complete Project
- `quickpoll-demo-complete.zip` - Full project with complete git history

### Documentation
- `QUICK-START.md` - Instructions for Tim (start here!)
- `TEACHER-GUIDE.md` - Comprehensive teaching guide
- `PROJECT-SUMMARY.md` - Technical overview
- `README.md` - This file

## 🚀 Getting Started

### Step 1: Extract & Setup
```bash
unzip quickpoll-demo-complete.zip
cd quickpoll-demo
npm install
npm run dev
```

### Step 2: Navigate to App
Open http://localhost:3000 in your browser

### Step 3: Jump Between Steps (During Teaching)
```bash
# View all available steps
git tag -l

# Jump to any step
git checkout stap-3

# See what changed in this step
git diff stap-2 stap-3

# Go to final version
git checkout bonus
```

## ✨ Key Features

- **9 Development Steps** - Logical progression from setup to full app
- **API Routes** - Backend routes in `/app/api`
- **Dynamic Routing** - `/poll/[id]` for individual poll pages
- **Real-Time Voting** - Vote and see results update instantly
- **Server Components** - Default Next.js 15 pattern
- **Client Components** - Interactive VoteForm with state
- **Error Handling** - Loading skeletons, error boundaries, 404 pages
- **TypeScript** - Fully typed throughout
- **Tailwind CSS** - Purple-themed responsive design
- **Middleware** - Request logging and timing
- **Demo Form** - Testing interface for API endpoints (stap-4)

## 📚 Documentation

### For Teachers
Start with **QUICK-START.md** - has everything you need before class

### For Understanding the Project
Read **PROJECT-SUMMARY.md** - complete technical overview

### For Teaching Details
See **TEACHER-GUIDE.md** - tips, key concepts, troubleshooting

## 🎯 Typical Class Flow

| Step | Duration | Focus |
|------|----------|-------|
| stap-0 to stap-2 | 15 min | File structure, homepage, cards |
| stap-3 | 10 min | API routes concept |
| stap-4 | 15 min | ⭐ Vote API demo (show DevTools!) |
| stap-5 to stap-6 | 15 min | Dynamic pages, voting interface |
| stap-7 to stap-8 | 10 min | Error handling, middleware |
| bonus | 10 min | Form handling, creating polls |

**Total: ~75 minutes for complete lesson**

## 💡 Key Teaching Moments

### stap-4: The Demo Form
This is your star moment! Show:
1. Demo form at http://localhost:3000/demo
2. Open DevTools Console - show logging
3. Switch to Network tab - show POST request
4. Click "Stem" and watch the request happen
5. Show the JSON response with updated votes

### stap-6: VoteForm Component
Explain:
- Why "use client" is needed (state management)
- How useState tracks selected option
- How fetch() sends vote to API
- How component updates when response comes back

### All Steps
Keep showing the running app - live feedback is key!

## 📋 What's in Each Step

### stap-0: Project Setup
- Create Next.js with TypeScript + Tailwind
- Define Poll interfaces
- Create mock data (3 sample polls)
- Set up folder structure

### stap-1: Layout & Navigation
- Add navbar with branding
- Set up global layout
- Add metadata

### stap-2: Homepage
- Display all polls as cards
- Show poll stats (option count, vote count)
- Add links to individual polls

### stap-3: API Routes
- `GET /api/polls` - fetch all polls
- `GET /api/polls/[id]` - fetch single poll
- `POST /api/polls` - create new poll

### stap-4: Vote API + Demo
- `POST /api/polls/[id]/vote` - record a vote
- Demo form at `/demo` for testing

### stap-5: Poll Detail Page
- Dynamic route `/poll/[id]`
- Dynamic metadata for SEO
- Show poll questions and options

### stap-6: VoteForm Component
- Client component with voting logic
- Real-time results with percentage bars
- Purple gradient progress bars

### stap-7: Error Handling
- Loading skeleton (Suspense)
- Error boundary component
- 404 pages

### stap-8: Middleware
- Request logging
- Timing middleware
- Route matching

### bonus: Create Poll
- Form to create new polls
- Dynamic option inputs
- Form validation
- Navigation after creation

## 🛠 Technology Stack

- **Next.js 15** - React framework
- **TypeScript** - Type-safe JavaScript
- **Tailwind CSS** - Utility-first CSS
- **React Hooks** - useState for interactivity
- **Fetch API** - For API calls
- **Git** - Version control with tags

## 🎨 Design System

**Purple Theme:**
- Primary: `#7c3aed` (purple-500)
- Hover: `#a855f7` (purple-600)
- Active: `#9333ea` (purple-700)

**Neutral:**
- Light backgrounds: Gray-50
- Text: Gray-900
- Borders: Gray-200
- Errors: Red-600

## ✅ Build & Deployment

### Verify Build
```bash
npm run build
```

### Deploy to Vercel
```bash
npm i -g vercel
vercel
```

One command deployment! (You need a Vercel account)

## 📌 Important Notes

### In-Memory Data
This project uses in-memory JavaScript arrays for data. In production, you'd use:
- PostgreSQL
- MongoDB
- Supabase
- Firebase

### No Authentication
This project doesn't have user accounts. Real apps would have:
- User authentication
- User-specific voting history
- Admin panels

### No Database
Each time you restart the app, votes reset. That's fine for demos!

## 🤔 Common Questions

**Q: Is this production-ready?**
A: No - it's designed for learning. Add a database for production.

**Q: Can I modify it for my class?**
A: Yes! Use it as a starting point for assignments.

**Q: How do I extend it?**
A: Add a real database (PostgreSQL with Prisma is popular), add authentication, add user accounts, etc.

**Q: Where can students learn more?**
A: https://nextjs.org/learn - official Next.js tutorial

## 📞 Support

Each zip file is independent and self-contained. You can:
1. Extract any `stap-X.zip` individually
2. Run `npm install` and `npm run dev`
3. See the app at that stage of development

The `quickpoll-demo-complete.zip` has git history, so you can:
1. `git log --oneline` - see all commits
2. `git checkout stap-3` - jump to any step
3. `git diff stap-2 stap-3` - see what changed

## 🎓 For Students

After the lesson, students can:
1. Clone the repo and explore the code
2. Modify styling with Tailwind
3. Add new features (poll deletion, editing, etc.)
4. Connect to a real database
5. Deploy to Vercel

This is a great foundation for learning full-stack web development!

## 📝 Notes

- All code in English (variable names, comments)
- UI text in Dutch (button labels, messages)
- Fully typed TypeScript throughout
- Comprehensive comments for teaching
- Clean, readable code style

## 🎉 Ready to Teach!

You have everything you need. Good luck with your live-coding demonstration!

Start with **QUICK-START.md** for immediate instructions.

---

**Version:** 1.0  
**Next.js:** 15.x  
**Node:** 18+ recommended  
**Date Created:** March 2026