Ship Better Code, Faster

Appearance

Workshop 4: Live demo script ​

Share-screen guide. Total time: ~15 minutes of guided fixes we do together, then ~15 minutes where we keep working through fixes together (students following in their own clones). Any item beyond the core fixes is optional polish, never required.

Setup before the demo ​

  • Pre-clone OrbitTasks fresh into ~/tmp/orbittasks-fresh so we can time a real "first-time-experience" together with the students.
  • Have the logbook open: we record the audit findings, fixes, and before/after times in the W4 logbook section together as we go.
  • Editor open.
  • Terminal open with time ready.

Step 1: Fix the broken setup script (~3 min) ​

  1. Run on screen:

    bash
    cd ~/tmp/orbittasks-fresh
bash scripts/setup.sh

  2. It runs without an obvious error, and that's the trap. mkdir -p logss is idempotent, so it never crashes; it just silently creates the wrong directory (logss instead of logs). And there's no seed step, so the app will have an empty DB and login will fail later.

    "Typo. One character. It doesn't even error; it just quietly makes the wrong folder. Two engineers haven't been able to onboard, and nobody knew why."

  3. Open scripts/setup.sh. Find the line: mkdir -p logss.

  4. Fix it on screen: mkdir -p logs. Commit.

  5. Note what's still missing: the env vars (Step 3) and the seed step (Step 2). The script "succeeds" but leaves you with a non-working app.

Step 2: Make the README honest (~5 min) ​

  1. Open README.md. Read the "Setup" section out loud.

    "Install. Start. That's it. Three lines. Now let's see what actually needs to happen."

  2. List the missing steps live, having students contribute from chat:

    • Copy .env.example to .env
    • Add JWT_SECRET (both this and DATABASE_URL are commented-out in .env.example)
    • Add DATABASE_URL (a file-backed JSON store, e.g. file:.data/orbittasks.json)
    • Run the seed step. This is required, not optional. The local DB starts empty, so login fails until you seed it: npm run seed --workspace=apps/api.
    • There is no root npm start / npm run dev; you run the two workspace dev servers.

  3. Rewrite the Setup section to match reality:

    markdown
    ## Setup

```bash
cp .env.example .env
# Edit .env to add JWT_SECRET and DATABASE_URL (see .env.example)
#   JWT_SECRET=any-random-string-for-local-dev
#   DATABASE_URL=file:.data/orbittasks.json
npm install

# Seed the database (required: local DB starts empty, login fails without it)
npm run seed --workspace=apps/api

# Run the two dev servers (there is no root start/dev script yet;
# adding one is part of the Makefile deliverable)
npm run dev --workspace=apps/api
npm run dev --workspace=apps/web
    
> "`SEED_ON_BOOT=1` exists, but it only runs on Render in the deployed environment. Locally you must seed by hand."

  4. Commit on screen.

Step 3: Complete .env.example (~2 min) ​

  1. Open .env.example. Show the bracketed comments: JWT_SECRET and DATABASE_URL are both there but commented out. Those are the two genuinely-missing/undocumented vars.

  2. Add the missing entries:

    JWT_SECRET=replace-me-with-a-random-string-for-local-dev
DATABASE_URL=file:.data/orbittasks.json

    "There's no SQLite here. DATABASE_URL points at a file-backed JSON store, a plain JSON file on disk. Under tests it's in-memory only."

  3. Commit.

Step 4: Delete the lying architecture doc (~2 min) ​

"This file talks about Postgres and Prisma. Neither of those are in the codebase anymore."

  1. Open docs/architecture.md.

  2. Replace with one truthful paragraph and a TODO list:

    markdown
    # OrbitTasks Architecture

OrbitTasks is a TypeScript monorepo with two apps:

- `apps/api/`: Node.js + Express backend, file-backed JSON store (JSON file via `DATABASE_URL`; in-memory only under tests).
- `apps/web/`: React + Vite frontend.

External services are mocked in tests via `scripts/mock-server.js`.

For deeper detail see the per-app READMEs.

  3. Commit.

Step 5: Build a working Makefile (~5 min) ​

  1. Create Makefile at the repo root:

    makefile
    .PHONY: setup dev test ci clean

setup:
	@cp -n .env.example .env || true
	@npm install

dev:
	@npm run dev --workspace=apps/api & npm run dev --workspace=apps/web

test:
	@npm test

ci:
	@bash scripts/measure.sh

clean:
	@rm -rf node_modules apps/*/node_modules apps/*/dist coverage baseline.log

  2. Demo make setup on the fresh clone. Time it. Target: under 90 seconds.

  3. Commit.

After the live demo ​

"Together we just brought onboarding from 'broken' to 'one command.' For the next 10 minutes we keep going together: pick one more fix from the audit and we work through it as a group, following along in your own clones. Record what you ship in your W4 logbook section as we go. We'll compare around the room."

That's the handoff to the next block. We keep working through fixes together rather than sending students off alone. Anything past the core fixes is optional polish.

Common things students will ask ​

"Should I use npm scripts or a Makefile?"

Either. The point is one command. We used a Makefile because it's polyglot. A team that's all-JavaScript might prefer npm scripts.

"Does this work on Windows?"

The Makefile won't, out of the box. You'd want to also provide an equivalent in npm scripts. Real teams support both.

"Why didn't the original devs do this?"

Real engineering. Nobody scheduled the work. The team grew faster than the documentation. That's why we're doing it now.