Milestone: Online Leaderboard Works

Before You Study (5 mins)

Lesson focus: Module C taught four things: AI products are API systems (Lesson 11), the frontend-backend boundary (Lesson 12), build your own REST API (Lesson 13), persist data with SQLite (Lesson 14). Today is the closing verification ritual — same shape as the Module B milestone, deeper system. By the end, your Snake game's real-time leaderboard works end-to-end: a player on one phone scores 1,200, a player on another phone refreshes the leaderboard, sees the new entry. That round-trip — phone → public URL → your container → your API → your database → back — is what every full-stack engineer ships, and you've now built every piece of it.

What you should have ready:

• Your full-stack system from Lessons 11-14: frontend (Snake game), backend (Express API), database (SQLite)
• Cloudflare Tunnel from Lesson 07 (or running again) to expose the system publicly
• Two devices ready — your laptop and your phone (or two phones)
• About 60 minutes
• One friend you can text the URL to — the social verification matters

The Concept

A full-stack milestone verifies that all the layers compose. Software engineering rewards composition: each lesson taught one piece in isolation; the milestone proves the pieces hold their shape when assembled. The pieces:

       ┌──────────────────┐                      ┌──────────────────────────────┐
       │  Phone / browser │  HTTPS / JSON        │  Your laptop                 │
       │  (frontend)      │ ─────────────────▶   │                              │
       │  Snake game      │                      │  Cloudflare Tunnel           │
       │  HTML/CSS/JS     │                      │  ────────────                │
       │                  │                      │  Docker container            │
       │                  │                      │  ────────────                │
       │                  │                      │  Express API (port 3001)     │
       │                  │                      │  ────────────                │
       │                  │                      │  SQLite (./data/scores.db)   │
       └──────────────────┘                      └──────────────────────────────┘
              │                                            │
              │ ◀────────────── leaderboard JSON ──────────┘
              ▼
       Player sees scores
       from everyone

Eleven lessons of work — Lessons 01 through 14 — collapsing into a single 200-millisecond round-trip when a phone in Mumbai requests /api/scores and gets back JSON containing scores written from a laptop on the other side of the room.

The discipline of a milestone is not "build something new." It is verify what you built actually works on a network you don't control. Three things commonly fail at this point and won't be obvious until you check:

1. The CORS configuration that worked locally may block the production domain. Your dev machine accepts http://localhost:3000; the real frontend now runs on https://your-tunnel.trycloudflare.com. The cors middleware needs to permit it.
2. The database file lives inside the Docker container. If the container restarts, the data may or may not persist depending on whether you mounted a volume. Production-grade systems use Docker volumes (-v ./data:/app/data); demo systems often forget and lose data on every container restart.
3. The LLM API key that lives in your local .env may not be inside the Docker container. Container builds don't copy .env by default (and shouldn't — secrets shouldn't bake into images). The right fix is to pass them at runtime: docker run -e GEMINI_API_KEY=....

Each of these three things is a real gotcha that catches every full-stack newcomer the first time. Hitting each of them once is part of the lesson.

The other thing milestones do is make the work shareable. By the end of Module C, you have a system worth showing — a real leaderboard, multi-user, public, persistent. The artefacts you produce today become the second portfolio entry of the course (after the Module B milestone). Two milestones into the curriculum, you have shipped more end-to-end software than most CS undergraduates ship in three years.

Quick Concepts

What We Will Build

By the end of this lesson, you will have done these specific things:

1. Verified the local dev stack — Snake game on http://localhost:3000, API on http://localhost:3001, calls succeed, scores persist across server restart. Run curl -s http://localhost:3001/api/scores | jq . — see real data.
2. Added a leaderboard UI to the Snake game — a sidebar or modal that shows the top 10 scores by score DESC. Update the leaderboard:
   • On page load (initial render).
   • Every 30 seconds via setInterval (so a player on one device sees scores from another player without manual refresh).
   • Immediately after the player's own score is submitted.
3. Containerized the backend with the database persistence baked in. Update your backend's Dockerfile:
   dockerfile

   Copy

   FROM node:20-alpine
   WORKDIR /app
   COPY package*.json ./
   RUN npm ci --only=production
   COPY . .
   RUN mkdir -p /app/data
   EXPOSE 3001
   CMD ["node", "server.js"]
   

   
   Build the image: docker build -t snake-backend .
4. Ran the container with a mounted volume so the SQLite file survives container restart:
   bash

   Copy

   docker run -d \
     --name snake-backend \
     -p 3001:3001 \
     -v $(pwd)/data:/app/data \
     -e GEMINI_API_KEY=your_real_key \
     snake-backend
   

   
   Stopped and restarted the container; verified scores persisted.
5. Tunneled both services — frontend on port 3000, backend on port 3001. Two terminal tabs:
   bash

   Copy

   cloudflared tunnel --url http://localhost:3000     # frontend tunnel
   cloudflared tunnel --url http://localhost:3001     # backend tunnel
   

   
   Got back two *.trycloudflare.com URLs.
6. Updated the frontend to point at the public backend URL instead of http://localhost:3001. Updated the backend's CORS to permit the public frontend URL.
7. Loaded the public frontend URL on your phone over mobile data. Played the game. Watched the score POST to the public backend, saved to SQLite inside the container running on your laptop, then read back via GET when the leaderboard refreshed. Felt the round-trip.
8. Sent the URL to a friend. They played the game. Their score appeared in your leaderboard. You played again; they refreshed; they saw your new score. The system is now multi-user.
9. Wrote the second MILESTONE.md — what you built, what you verified, who played, what surprised you. This becomes the second portfolio entry alongside the Module B MILESTONE.md.

The "felt the round-trip" in step 7 is the moment that matters. Until then, full-stack is a diagram; after it, full-stack is a thing your hands have built.

Think About

Before studying, consider:

1. The Module B milestone proved your frontend worked from anywhere on the internet. The Module C milestone proves the full system (frontend + backend + database) works for multiple users at once. What further capability would the Module D milestone need to demonstrate? (Hint: AI features, polish, documentation, real users.)
2. Your leaderboard right now has one obvious vulnerability — anyone can submit any score they want, including 999,999,999. Your validation rejects negative numbers but not absurdly large ones. What real-world products do to defend against this? (Hint: server-side game-state validation, rate limits, signed receipts. The defense is technical and social — and once you ship something with users, you start caring about it.)

By the End

After this lesson, you'll:

• Have a leaderboard UI that updates live (every 30 seconds + immediately after submission)
• Have your backend containerized with a mounted volume so data persists
• Have both frontend and backend tunneled with public HTTPS URLs
• Have CORS configured for the production origin (not just localhost)
• Have played the game on your phone, scored, and watched it appear in the leaderboard
• Have a friend's score appear in your leaderboard — the multi-user moment
• Have a second MILESTONE.md capturing the achievement
• Be ready for Module D — adding AI features and polish to the system you just built

Module C composes. Eleven lessons, one running system, real users. 🔗

What We Learned

• A milestone is the verification ritual that proves the parts compose. Each Module C lesson taught one layer in isolation; today proved they hold their shape when assembled.
• Three real gotchas catch every full-stack newcomer at this point: CORS configuration that needs the production origin, Docker volumes for persistent data, environment variables passed at runtime not baked into images. Hitting each once is part of the curriculum.
• The full round-trip — phone → tunnel → container → API → database → back — happens in ~200 milliseconds. Everything you've practiced for 15 lessons lives inside that round-trip.
• Multi-user changes everything. As soon as two devices share a system, the database is the source of truth, race conditions become possible, and the engineering disciplines you'll learn in Module D and beyond start mattering.
• Document what you build, every milestone. A 100-word MILESTONE.md per major checkpoint becomes the visible evidence of progress that future-you, hiring managers, and collaborators can read in 60 seconds.

Commands We Used

# Build the backend image with database support
cd backend
docker build -t snake-backend .

# Run the container with a host-mounted data volume
# Without -v, the SQLite file lives inside the container and disappears on restart.
# With -v, the file lives on your host and survives.
docker run -d \
  --name snake-backend \
  -p 3001:3001 \
  -v $(pwd)/data:/app/data \
  -e GEMINI_API_KEY="$GEMINI_API_KEY" \
  snake-backend

# Verify the container is healthy
docker ps
docker logs -f snake-backend                          # follow logs

# Two parallel tunnels — one per service
cloudflared tunnel --url http://localhost:3000        # frontend
cloudflared tunnel --url http://localhost:3001        # backend

# Verify the public backend works
curl -s https://your-backend-tunnel.trycloudflare.com/api/scores | jq .

# Restart the container — data should persist
docker restart snake-backend
curl -s https://your-backend-tunnel.trycloudflare.com/api/scores | jq .

The final CORS configuration in server.js (the production-correct one):

import cors from 'cors'

const allowedOrigins = [
  'http://localhost:3000',
  'https://your-frontend-tunnel.trycloudflare.com',     // your public URL
  // Once you add a custom domain, that goes here too
]

app.use(cors({
  origin: (origin, callback) => {
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true)
    } else {
      callback(new Error('Not allowed by CORS'))
    }
  }
}))

A starter MILESTONE.md for Module C:

# Module C Milestone — Online Leaderboard, Multi-User

**Date completed:** YYYY-MM-DD
**Frontend URL:** https://my-frontend.trycloudflare.com (ephemeral)
**Backend URL:** https://my-backend.trycloudflare.com (ephemeral)
**GitHub:** https://github.com/<my-user>/snake-game
**Demo screen recording:** [link to file or YouTube]

## What's deployed

- Snake game frontend, served via Cloudflare Tunnel (Lessons 06-07)
- Express.js backend with REST API (Lesson 13)
- SQLite database in a Docker volume (Lesson 14)
- LLM-powered "Quote of the Day" call routed through the backend (Lessons 11-12)

## What I verified

- [x] Played the game from my phone on mobile data — scored, saved, displayed
- [x] A friend played from their device — their score appeared in my leaderboard
- [x] Restarted the container — scores survived (volume is working)
- [x] Restarted the laptop — game offline (laptop is the production server today)
- [x] Tested every API endpoint with curl
- [x] Validation rejects malformed scores (negative, NaN, missing name)

## What surprised me

(1-3 things you learned during the verification ritual that you didn't expect.)

## What I'd do differently

(1-2 changes with hindsight.)

## Next: Module D — AI Product Practice

Why It Matters

Module C is the architectural inflection point of the curriculum. Before today, you were building a frontend — a thing that ran on one user's machine. From today, you build systems — things that have a server-side component, a persistent state, a multi-user reality. Most software in the world is server-side; most career roles in software are server-side; most of the leverage in modern computing is server-side.

The deeper professional insight: everything in modern engineering is composition. No project ships from one engineer's laptop in isolation; every project assembles primitives — your code, third-party libraries, cloud services, model APIs — into a working system. The discipline of checking that the assembly actually composes correctly is the ritual you practiced today, and it's a discipline that scales: a 50-person team's release process is the same shape as your milestone, just with more verification surfaces.

What this lesson glossed over but you'll meet:

• Real hosting — your laptop is the production server today. In Module D and your post-course work, the server moves to a managed VPS, Cloudflare Workers, AWS, or similar. The disciplines transfer.
• CI/CD pipelines — you deploy by manually rebuilding the container today. The next step is GitHub Actions auto-deploying on every push to main.
• Observability at scale — console.log and docker logs work for one server; production systems use centralized logging (Datadog, Cloudwatch, Loki), distributed tracing (OpenTelemetry), and on-call rotations.
• Security beyond CORS — auth, rate limiting, input sanitization, dependency audits. Module D doesn't fully cover all of this, but the disciplines you've already practiced (validation, server-side secrets, prepared SQL statements) are the foundation.
• Database migrations — schemas evolve. The IF NOT EXISTS pattern works for adding tables; ALTER TABLE migrations are how you safely add columns to a table that already has data.

The biggest mental shift today: you have built a system whose pieces are independently meaningful and collectively useful. Eleven lessons, four primitives (frontend, backend, database, API call), one running multi-user product. From here, every project you ship in your career is a variation on this architecture.

Checklist

• My leaderboard UI updates on page load and every 30 seconds
• My backend container has a mounted data/ volume; scores survive docker restart
• Both frontend and backend are tunneled with public HTTPS URLs
• CORS allows my public frontend origin (not just localhost)
• I played the game on my phone over mobile data; my score appeared
• A friend played from a different device; their score appeared in my leaderboard
• I tested validation: a malformed POST returns 400 with a clean error message
• My API key was passed via -e GEMINI_API_KEY=... at docker run time, not baked into the image
• I wrote MILESTONE.md documenting what was built, what was verified, what surprised me

Quick Quiz

Q1: Why is testing on mobile data important?

• A) Mobile data is faster
• B) It reproduces the experience of an external user — different network, different DNS path ✓
• C) WiFi blocks Cloudflare

Q2: What does mounting a Docker volume (-v ./data:/app/data) accomplish?

• A) It makes the container faster
• B) The data lives on the host filesystem instead of inside the container, so it survives container restart ✓
• C) It encrypts the data

Q3: Why pass secrets like GEMINI_API_KEY at runtime instead of baking them into the image?

• A) Runtime injection is faster
• B) Images are commonly shared (registries); secrets baked into an image leak whenever the image is shared ✓
• C) Images can't store environment variables

Q4: What does CORS need in production that it didn't in development?

• A) A faster encryption algorithm
• B) An explicit allowlist of the production frontend's origin (not just localhost) ✓
• C) Nothing — CORS only matters in development

Q5: What is the discipline this milestone reinforces?

• A) Always test the full composition on a network you don't fully control before declaring done ✓
• B) Always use Docker for everything
• C) Always use SQLite over PostgreSQL

Bonus Challenge

Stress-test your own system. Open your backend tunnel URL in five browser tabs simultaneously. In each, submit a score every second for one minute. Watch the database. Watch your container's logs. Two outcomes:

1. Everything keeps working — congratulations, your simple system handles small concurrent load fine. SQLite in WAL mode is genuinely good at this.
2. Something breaks — also valuable. Maybe a race condition, maybe a connection limit, maybe the container runs out of memory. Each break is a real lesson about the limits of the system you've built.

Either outcome teaches you something true about the system. Senior engineers do this routinely; it's how they know the operational limits of what they ship.

Next Lesson — opening Module D

Lesson 16: Adding AI to YOUR App

Module C is complete. You have built every layer of a multi-user web application. Module D — AI Product Practice (Lessons 16-20) takes the system you just built and turns it into a real AI product. AI as a feature with bounded behavior, prompt engineering, professional documentation, final polish, and the graduation lesson that helps you choose what to specialize in next.

Today's lesson made you a full-stack engineer. The next module makes you an AI product engineer.

Module C complete. Three modules built; one to go. 🏆