novi-lessons/Les06-NextJS-QuickPoll-Part2/demo-zips/TEACHER-GUIDE.md

# QuickPoll Next.js Demo - Live Coding Guide for Tim

## Overview

This is a complete, step-by-step Next.js 15 project built for live-coding demonstrations. Each step has a git tag, allowing you to jump between different stages of the application during class.

## File Structure

```
demo-output/
├── 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 all, GET single, POST create)
├── stap-4.zip                       # POST vote route + demo form
├── stap-5.zip                       # Poll detail page
├── stap-6.zip                       # VoteForm component
├── stap-7.zip                       # Loading, error, not-found pages
├── stap-8.zip                       # Middleware
├── bonus.zip                        # Create poll page
└── quickpoll-demo-complete.zip      # Full project with complete git history
```

## How to Use in Live-Coding Class

### 1. **Setup Before Class**

Extract `quickpoll-demo-complete.zip`:

```bash
unzip quickpoll-demo-complete.zip
cd quickpoll-demo
npm install
```

### 2. **Jump Between Steps During Class**

Use git checkout to jump to any step:

```bash
# Go to beginning (step 0)
git checkout stap-0

# Progress to step 1
git checkout stap-1

# Jump to step 4 to show the demo form
git checkout stap-4

# Go back to the final version
git checkout bonus
```

### 3. **Run the Application**

```bash
npm run dev
```

Then open `http://localhost:3000` in your browser and use the projector to show students.

### 4. **Show the Demo Form (stap-4)**

When you checkout `stap-4`, a demo page is available at `http://localhost:3000/demo`:

- Show students how to use the form to test the vote API
- Open DevTools (F12) → Network tab to show the POST request
- Open Console to show the console.log messages
- Display the fetch code example to teach how API calls work

## What Each Step Covers

### stap-0: Project Setup
- Create Next.js project with TypeScript and Tailwind
- Set up types and data structures
- Initial folder structure with in-memory "database"
- Includes `.cursorrules` for consistent code style

**Files to show:**
- `src/types/index.ts` - Poll and VoteBody interfaces
- `src/lib/data.ts` - Sample polls data and functions

### stap-1: Layout & Navigation
- Add navbar with QuickPoll branding
- Add navigation links (Home, Nieuwe Poll in bonus)
- Update metadata and HTML structure
- Global Tailwind styling

**Files to show:**
- `src/app/layout.tsx` - Layout component with navbar

### stap-2: Homepage
- Display all polls as cards
- Show poll question, number of options, total votes
- Add hover effects and links to poll detail pages

**Files to show:**
- `src/app/page.tsx` - Homepage with poll cards grid
- Tailwind classes for responsive design

### stap-3: API Routes
- Create `GET /api/polls` - fetch all polls
- Create `GET /api/polls/[id]` - fetch single poll
- Create `POST /api/polls` - create new poll
- Use Next.js 15 async params pattern

**Files to show:**
- `src/app/api/polls/route.ts`
- `src/app/api/polls/[id]/route.ts`
- Point out `params: Promise<{ id: string }>` pattern

### stap-4: Vote API Route + Demo Form
- Create `POST /api/polls/[id]/vote` - vote on a poll
- Input validation and error handling
- **Demo form at `/demo`** - interactive testing page
- Console.log statements for teaching
- Display fetch code example

**Files to show:**
- `src/app/api/polls/[id]/vote/route.ts`
- `src/app/demo/page.tsx` - the demo form (use projector!)
- DevTools Console to show logging
- DevTools Network tab to show POST requests

### stap-5: Poll Detail Page
- Create `src/app/poll/[id]/page.tsx` (Server Component)
- Add `generateMetadata()` for dynamic SEO
- Use `notFound()` for missing polls
- Placeholder for VoteForm (comes next)

**Files to show:**
- `src/app/poll/[id]/page.tsx`
- Point out that this is a Server Component (no "use client")

### stap-6: VoteForm Component
- Create `src/components/VoteForm.tsx` ("use client")
- Implement voting with state management
- Show results after voting with percentage bars
- Purple theme (#7c3aed) with gradient progress bars
- Real-time vote count updates

**Files to show:**
- `src/components/VoteForm.tsx`
- Explain useState and fetch inside a component
- Show console.log for vote submissions
- Update to `src/app/poll/[id]/page.tsx` to use VoteForm

### stap-7: Error Handling Pages
- Create `src/app/loading.tsx` - skeleton loader
- Create `src/app/error.tsx` - error boundary
- Create `src/app/not-found.tsx` - global 404 page
- Create `src/app/poll/[id]/not-found.tsx` - poll-specific 404

**Files to show:**
- Explain Suspense boundaries and error handling
- Show how Next.js automatically uses these files

### stap-8: Middleware
- Create `src/middleware.ts` - request logging
- Log request timing and paths
- Use matcher for selective routes

**Files to show:**
- `src/middleware.ts`
- Point out the matcher configuration

### bonus: Create Poll Page
- Create `src/app/create/page.tsx` - full form with validation
- Dynamic option inputs (add/remove)
- POST to `/api/polls` and redirect
- Remove demo page (was temporary for stap-4)
- Add "Nieuwe Poll" link to navbar

**Files to show:**
- `src/app/create/page.tsx` - form implementation
- Error handling and validation

## Teaching Tips

### Code Highlighting
- Use VS Code theme with good contrast on projector
- Increase font size (at least 16-18pt)
- Use "Zen Mode" or "Fullscreen" for less distraction

### Live Coding Strategy
1. **Type slowly** - Let students follow along
2. **Explain as you type** - Narrate what you're doing
3. **Run often** - Show working results frequently
4. **Use DevTools** - Show Network and Console tabs
5. **Ask questions** - Make it interactive

### DevTools Demonstrations

**When showing stap-4 demo:**
1. Open http://localhost:3000/demo
2. Open DevTools (F12)
3. Go to Console tab - show console.log messages
4. Go to Network tab
5. Fill the form and click "Stem"
6. Show the POST request in Network tab
7. Show the JSON response
8. Check the Console for detailed logging

### Key Concepts to Teach

- **Server Components vs Client Components** - explain when to use "use client"
- **Dynamic Routes** - show how `[id]` creates dynamic pages
- **API Routes** - show how `/api` routes handle requests
- **Middleware** - show how to run code before requests
- **Tailwind CSS** - explain utility-first CSS
- **State Management** - useState in VoteForm
- **Fetch API** - how components communicate with API

### Projector Tips
- Test the layout on a real projector before class
- Use a light theme for better visibility
- Zoom in on code snippets (Ctrl/Cmd + in browser)
- Keep demos simple - don't try to build everything from scratch

## File Sizes
- `stap-0.zip` to `stap-8.zip`: ~32-43 KB each
- `bonus.zip`: ~44 KB
- `quickpoll-demo-complete.zip`: ~160 KB (includes full git history)

## Git Commands for Students

After you show them the steps, students can explore:

```bash
# See all commits
git log --oneline

# See all tags
git tag -l

# Jump to a specific step
git checkout stap-3

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

# Go back to latest
git checkout bonus
```

## Troubleshooting

### Port 3000 already in use
```bash
npm run dev -- -p 3001
```

### Changes not showing
```bash
# Hard refresh in browser
Ctrl+Shift+R (Windows/Linux)
Cmd+Shift+R (Mac)
```

### Git checkout doesn't work
```bash
# Make sure you're in the project directory
cd quickpoll-demo

# See current status
git status

# If you have uncommitted changes
git stash

# Then try checkout again
git checkout stap-5
```

### Build errors
```bash
# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
npm install

# Try building
npm run build
```

## Project Structure Notes

- **src/app/** - Next.js App Router pages and layouts
- **src/components/** - Reusable React components
- **src/lib/** - Utility functions and mock data
- **src/types/** - TypeScript interfaces
- **src/middleware.ts** - Request middleware
- **public/** - Static assets

## Additional Resources

- Next.js 15 docs: https://nextjs.org/docs
- Tailwind CSS: https://tailwindcss.com/docs
- React: https://react.dev

## Next Steps After the Demo

Students can:
1. Modify poll questions and options
2. Add new features (e.g., poll deletion, editing)
3. Connect to a real database (PostgreSQL, MongoDB, etc.)
4. Add authentication
5. Deploy to Vercel

Good luck with your live-coding demonstration! 🎉