From Vibe Coder
to Professional Developer

tsm@mac ~ %  # This is your prompt. ~ means your home directory.

PS C:\Users\you>  # PS = PowerShell. C:\Users\you is your home directory.

The most important commands for navigating:

Run these in order. Don't skip ahead — each step may depend on the previous one.

xcode-select --install

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install nvm
# Add nvm to your shell (follow the output instructions)
nvm install 20
nvm use 20
nvm alias default 20
node --version  # should print v20.x.x
npm --version

brew install git
git --version
# Configure your identity
git config --global user.name "Your Name"
git config --global user.email "you@codeimpact.ai"

npm install -g @anthropic-ai/claude-code
claude --version

docker --version
docker compose version

# Verify winget is available:
winget --version
# If not found, update "App Installer" in the Microsoft Store

# Install nvm-windows via winget:
winget install CoreyButler.NVMforWindows
# Close and reopen Windows Terminal, then:
nvm install 20
nvm use 20
node --version  # should print v20.x.x
npm --version

winget install Git.Git
# Close and reopen Windows Terminal, then:
git --version
# Configure your identity
git config --global user.name "Your Name"
git config --global user.email "you@codeimpact.ai"

npm install -g @anthropic-ai/claude-code
claude --version

docker --version
docker compose version

A Code Impact project has a frontend and a backend — and each has its own set of variables. Keep them in one .env file at the repo root, divided by commented sections so it's clear which vars belong where:

# ── BACKEND ──────────────────────────────
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
JWT_SECRET=any-local-string
PORT=3000
NODE_ENV=development

# ── FRONTEND ─────────────────────────────
VITE_API_URL=http://localhost:3000

Every project has a .env.example that lists all required variables — both frontend and backend sections — without real values. When you clone a project, copy it to .env and fill in real values:

cp .env.example .env
# Now edit .env with your actual secrets

Every Code Impact project uses npm scripts to run common tasks. You'll see these patterns in every repo:

# Install all dependencies
npm install

# Start the development server
npm run dev

# Build for production
npm run build

# Run tests
npm run test

# Lint the code
npm run lint

# TypeScript type check
npm run typecheck

These are defined in package.json — always check that file when you join a new project.

Download VS Code at code.visualstudio.com. Once installed, open it and install these extensions (Cmd+Shift+X to open Extensions panel):

Then add this to your VS Code settings.json (Cmd+Shift+P → "Open User Settings JSON"):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.tabSize": 2,
  "editor.fontSize": 14,
  "js/ts.preferences.importModuleSpecifier": "relative",
  "files.trimTrailingWhitespace": true
}

Every Code Impact project follows a consistent folder structure. Here's what you'll see:

my-project/
├── frontend/          # React app (Vite)
│   └── src/
│       ├── pages/     # Full-page components
│       ├── components/ # Reusable UI pieces
│       ├── hooks/     # Custom React hooks
│       ├── lib/       # Utility functions
│       └── types/     # TypeScript definitions
├── backend/           # Node.js/Express API
│   └── src/
│       ├── controllers/ # Route handlers (thin)
│       ├── services/  # Business logic (fat)
│       ├── routes/    # Express route definitions
│       ├── middleware/ # Auth, error handling
│       └── utils/     # Shared helpers
├── backend/prisma/    # Database schema + migrations
├── docs/              # Reference documentation
├── CLAUDE.md          # ★ Claude reads this every session
├── .env               # ★ NEVER committed to Git
├── .env.example       # ★ Always committed (no real values)
└── package.json       # Scripts and dependencies

Think of Git as a timeline of snapshots. Every time you commit, you save a snapshot of your code. You can go back to any snapshot at any time. GitHub hosts your timeline in the cloud.

# --- Starting work ---
git clone https://github.com/org/repo.git  # Download a repo
git status                                  # See what's changed
git pull                                    # Get latest from remote

# --- Saving work ---
git add filename.ts                         # Stage a specific file
git add .                                   # Stage all changes (use carefully)
git commit -m "feat(auth): add login form"  # Commit with a message
git push                                    # Upload to GitHub

# --- Branches ---
git branch                                  # List all branches
git checkout -b feat/42-user-login          # Create + switch to new branch
git checkout main                           # Switch back to main
git merge feat/42-user-login                # Merge a branch in

# --- Inspecting ---
git log --oneline                           # See commit history
git diff                                    # See unstaged changes
git diff --staged                           # See staged changes

At Code Impact, every commit follows this format. It keeps the history readable and makes automated changelogs possible.

type(scope): short description
feat(auth): add JWT refresh token rotation
fix(api): handle null user in getProfile
chore(deps): upgrade react to 19.1
docs(readme): add Railway deployment steps
test(auth): add coverage for login failure case
refactor(services): extract email to shared util

This is the workflow for every single feature at Code Impact. Nothing goes directly to main.

The commands in full:

# Start a new branch for your issue
git checkout -b feat/42-short-title

# Stage and commit as you work
git add .
git commit -m "feat(scope): description"

# Push to GitHub and open a PR
git push -u origin feat/42-short-title

# After the PR is merged — sync main
git checkout main
git pull

Create a GitHub account if you don't have one. Then set up SSH authentication so you don't have to type your password every time you push:

# Generate an SSH key
ssh-keygen -t ed25519 -C "you@codeimpact.ai"
# Press Enter for all prompts

# Copy the public key to your clipboard
cat ~/.ssh/id_ed25519.pub | pbcopyGet-Content ~/.ssh/id_ed25519.pub | Set-Clipboard
# Then go to GitHub → Settings → SSH and GPG keys → New SSH key
# Paste your key and save

# Test the connection
ssh -T git@github.com

Claude Code is an agentic coding assistant that runs in your terminal. Unlike copy-pasting from a chat interface, Claude Code can read your files, run commands, edit code, and execute project scripts — all with your oversight. It is not autopilot. You remain the architect.

# Install Claude Code globally (one-time):
npm install -g @anthropic-ai/claude-code

# Start Claude Code inside any project folder:
claude

# Run a one-shot question:
claude "what does this project do?"

# Run a slash command:
/feature-start 42

CLAUDE.md sits at the root of every Code Impact project. Claude Code reads it automatically at the start of every session. It is the project's constitution — stack, commands, standards, architecture, known gotchas. Read it before writing a single line on any project.

# CLAUDE.md — code-impact-training (example)

## Project
- What: Training repo — full-stack app built through the Code Impact curriculum
- Stack: Node.js/TypeScript — React (Vite) frontend + Express API
- Database: PostgreSQL via Prisma (Railway)
- Deploy: Railway via Docker, CI/CD via GitHub Actions

## Commands
npm run dev        # Start dev server
npm run test       # Jest tests
npm run lint:fix   # ESLint auto-fix
npm run typecheck  # tsc --noEmit

## Code Standards
- No any types — use unknown and narrow
- Controller → Service → Prisma (never put business logic in controllers)
- Never console.log in production — use the structured logger

## Architecture
- Frontend: React + Vite + TypeScript + Tailwind, port 5173
- Backend: Express + TypeScript, port 3001

## Known Gotchas
- Run migrations before starting the backend: npx prisma migrate dev
- .env is never committed — copy .env.example and fill in real values

The single most important habit in the Code Impact workflow: never start building until you have an approved plan. Plan Mode lets Claude analyze the codebase and propose an approach — without writing any code yet. You review and approve (or push back) before a single file is touched.

# Tell Claude to use Plan Mode before writing any code:
"Before writing anything, give me a plan for adding user authentication.
Use Plan Mode — list the files you'll touch, the order of operations,
and any risks. I'll approve before you start."

A good plan includes:

Git worktrees are how Code Impact works on multiple features at the same time without branches stepping on each other. Each feature gets its own directory on disk — a full checkout of the repo, on its own branch, completely isolated.

The Directory Structure

Worktrees live as siblings to the main project directory — never inside it. /feature-start creates them automatically with a consistent naming convention.

~/Documents/
├── code-impact-training/              # ★ Main project (VS Code Window 1)
├── code-impact-training-feat-42/      # ★ Worktree for issue #42 (Window 2)
└── code-impact-training-feat-51/      # ★ Worktree for issue #51 (if needed)

The Two VS Code Windows Rule

This is a hard rule, not a suggestion. Every worktree gets its own VS Code window.

Terminal State Checklist

Before writing a single line of code in a worktree, run these three checks. All three must pass.

# Check 1 — Are you in the right directory?
pwd
# Expected: /Users/you/Documents/code-impact-training-feat-42
# NOT: /Users/you/Documents/code-impact-training — wrong!

# Check 2 — Are you on the right branch?
git branch
# Expected: * feat/42-add-auth
# NOT: * main — wrong!

# Check 3 — Does .env exist?
ls .env
# Expected: .env
# If missing: cp ../code-impact-training/.env .env

/clean-worktree — After the PR Merges

After a PR is merged, the worktree is done. Run /clean-worktree from the main project window to remove it cleanly.

# In Window 1 (main project), after PR is merged:
/clean-worktree 42

# This command:
# 1. Removes the worktree from Git tracking (git worktree remove)
# 2. Deletes the directory on disk
# 3. Prunes the remote branch reference

Every feature at Code Impact follows the same loop. Each step is a Claude Code slash command. These aren't suggestions — they're the workflow. Running them in order is what makes PRs mergeable and deployments predictable.

The Feature Loop (run in this order)

Each step hands off to the next. /build-feature is the only command that calls another command internally (/verify) because testing is part of the build, not a separate gate. Everything else is human-initiated.

All 18 Commands — Quick Reference

These are the three rules the team never breaks. They exist because the times they were ignored cost hours of lost work. Memorize them.

The 3 Hard Rules

The Morning Ritual — /parallel-status

Before touching any code, every morning starts with one command from the main project window:

# From Window 1 (main project), every morning:
/parallel-status

# Output shows:
# Active worktrees and which issue they're tracking
# PR status for each: draft / in review / approved / merged
# Any PRs from teammates awaiting your review
# Whether you're clear to start new work

Keeping Your Branch Current

# Every morning, in each active worktree (Window 2):
git fetch origin
git merge origin/main -m "Merging main into branch"

# This keeps your feature branch current.
# /create-pr does this automatically — but do it daily
# to catch conflicts while they're still small.

Day One Checklist

When you join Code Impact and get access to your first real project:

TypeScript is JavaScript with types. The types catch bugs before they happen. At Code Impact: strict mode, no any, use unknown when unsure.

// Types
type User = {
  id: string
  name: string
  email: string
  createdAt: Date
}

// Functions with typed params + return
function greet(user: User): string {
  return `Hello, ${user.name}`
}

// Arrays and optionals
type Task = {
  id: string
  title: string
  completed: boolean
  dueDate?: Date    // ? means optional
  tags: string[]   // array of strings
}

// Enums
type Status = 'todo' | 'in_progress' | 'done'

// Generics — a function that works with any type
function first<T>(arr: T[]): T | undefined {
  return arr[0]
}

React builds UIs from components. At Code Impact: functional components only, named exports, hooks over classes.

// A typed React component
type TaskCardProps = {
  task: Task
  onComplete: (id: string) => void
}

export function TaskCard({ task, onComplete }: TaskCardProps) {
  return (
    <div className="p-4 bg-white rounded-lg shadow">
      <h3>{task.title}</h3>
      <button onClick={() => onComplete(task.id)}>
        Mark done
      </button>
    </div>
  )
}

// useState — local component state
import { useState } from 'react'

export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
}

// useEffect — side effects (fetching, subscriptions)
import { useEffect, useState } from 'react'

export function TaskList() {
  const [tasks, setTasks] = useState<Task[]>([])

  useEffect(() => {
    fetch('/api/v1/tasks')
      .then(r => r.json())
      .then(data => setTasks(data.data))
  }, []) // [] = run once on mount

  return <ul>{tasks.map(t => <li key={t.id}>{t.title}</li>)}</ul>
}

The backend is a Node.js server built with Express. It follows a strict 3-layer pattern: Controller → Service → Prisma (database).

// routes/tasks.ts — just wires up endpoints
import { Router } from 'express'
import { TaskController } from '../controllers/taskController'

const router = Router()
router.get('/', TaskController.getAll)
router.post('/', TaskController.create)
router.patch('/:id', TaskController.update)
export { router }

// controllers/taskController.ts — thin, delegates to service
export const TaskController = {
  getAll: async (req, res) => {
    const tasks = await TaskService.getAll(req.user.id)
    res.json({ success: true, data: tasks })
  }
}

// services/taskService.ts — all the logic lives here
export const TaskService = {
  getAll: async (userId: string) => {
    return prisma.task.findMany({
      where: { userId },
      orderBy: { createdAt: 'desc' }
    })
  }
}

Code Impact uses Vitest for unit tests. It has the same API as Jest (describe, it, expect) and works natively with TypeScript. Install it in the backend:

npm install -D vitest

Add a test script to backend/package.json:

{
  "scripts": {
    "test": "vitest run"
  }
}

All tests live in a tests/ directory at the backend root — not scattered through the source tree. Create it once and all test files go there. Here's an example testing a pure helper function:

// src/services/taskService.ts
export function isOverdue(dueDate: Date): boolean {
  return dueDate < new Date()
}

// tests/taskService.test.ts
import { describe, it, expect } from 'vitest'
import { isOverdue } from '../src/services/taskService'

describe('isOverdue', () => {
  it('returns true when due date is in the past', () => {
    const past = new Date(Date.now() - 86400000)
    expect(isOverdue(past)).toBe(true)
  })
  it('returns false when due date is in the future', () => {
    const future = new Date(Date.now() + 86400000)
    expect(isOverdue(future)).toBe(false)
  })
})

Run tests from the backend directory:

npm run test

Prisma is the database toolkit. You define your data model in schema.prisma, run a migration, and Prisma generates fully-typed database functions.

// prisma/schema.prisma — source of truth for data
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String
  tasks     Task[]
  createdAt DateTime @default(now())
}

model Task {
  id        String   @id @default(cuid())
  title     String
  status    Status   @default(TODO)
  userId    String
  user      User     @relation(fields: [userId], references: [id])
  dueDate   DateTime?
  createdAt DateTime @default(now())
}

enum Status {
  TODO
  IN_PROGRESS
  DONE
}

# After changing the schema, always run:
npx prisma migrate dev --name "add-task-due-date"
npx prisma generate    # Regenerate TypeScript types

// Querying with Prisma — fully typed
const tasks = await prisma.task.findMany({
  where: { userId, status: 'TODO' },
  orderBy: { createdAt: 'desc' },
  take: 20   // limit results
})

const task = await prisma.task.create({
  data: { title, userId, status: 'TODO' }
})

await prisma.task.update({
  where: { id: taskId },
  data: { status: 'DONE' }
})

Every Code Impact production project runs in Docker. Both the frontend and backend are containerized so they behave identically on your Mac, in CI, and on Railway. This lesson teaches you to write Dockerfiles from scratch and wire them together with Compose.

5a — What Docker Actually Does

Docker packages your app and everything it needs (Node version, system libraries, config) into an image. When you run the image, it becomes a container — an isolated process that behaves the same on every machine. Docker Compose orchestrates multiple containers together as a stack.

5b — Writing a Backend Dockerfile

The backend Dockerfile is a production build — it compiles TypeScript to JavaScript, then starts the compiled output. This is the same image used locally and on Railway. Pin the Node version — never use latest.

# backend/Dockerfile
FROM node:20-alpine

WORKDIR /app

# Copy package files first — Docker caches this layer
# if they haven't changed (faster rebuilds)
COPY package*.json ./
RUN npm ci

COPY . .

# Compile TypeScript → dist/
RUN npm run build

EXPOSE 3000

CMD ["node", "dist/server.js"]

5c — Writing a Frontend Dockerfile

The frontend Dockerfile follows the same pattern — install deps and run the Vite dev server.

# frontend/Dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

EXPOSE 5173

CMD ["npm", "run", "dev"]

5d — Docker Compose: The Full Local Stack

Compose wires the frontend, backend, and a local PostgreSQL database together. The db service runs Postgres in a container — no installation required. The backend depends on it starting first.

# docker-compose.yml
services:

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=orbit
    ports:
      - "5432:5432"  # Exposed so you can run prisma migrate dev from your terminal
    volumes:
      - db_data:/var/lib/postgresql/data  # Persist data between restarts

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:password@db:5432/orbit  # Uses service name, not localhost
      - JWT_SECRET=${JWT_SECRET}
    depends_on:
      - db

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
      args:
        - VITE_API_URL=http://localhost:3000
    ports:
      - "5173:5173"
    depends_on:
      - backend

volumes:
  db_data:

5e — Essential Docker Commands

5f — The .dockerignore File

Like .gitignore but for Docker builds. Always have one — it stops node_modules and secrets from being accidentally copied into images.

# .dockerignore (put in both frontend/ and backend/)
node_modules
dist
build
.env
.env.*
*.test.ts
*.spec.ts
coverage
.git
.DS_Store

Here's a complete CI workflow for a monorepo with frontend and backend:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: ['**']          # Run on every push to any branch
  pull_request:
    branches: [main]

jobs:
  backend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: backend/package-lock.json
      - run: npm ci
        working-directory: backend
      - run: npm run lint
        working-directory: backend
      - run: npm run typecheck
        working-directory: backend
      - run: npm run test
        working-directory: backend
      - run: npm run build
        working-directory: backend

  frontend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
        working-directory: frontend
      - run: npm run lint
        working-directory: frontend
      - run: npm run typecheck
        working-directory: frontend
      - run: npm run build
        working-directory: frontend

NODE_ENV — How Apps Change Behaviour

The NODE_ENV environment variable tells your app which mode it's running in. Apps use this to change behaviour automatically:

// In production: hide error details from users
if (process.env.NODE_ENV === 'production') {
  res.json({ error: 'Something went wrong' })
} else {
  res.json({ error: err.message, stack: err.stack })  // local only
}

How to set up a project from scratch

You create the project once, then configure each environment inside it. Here's the setup flow:

railway.toml

Commit this to the repo root. It tells Railway which Dockerfile to build and how to start the server:

# railway.toml (at repo root)
[build]
builder = "dockerfile"
dockerfilePath = "backend/Dockerfile"

[deploy]
healthcheckPath = "/health"
healthcheckTimeout = 300
startCommand = "npx prisma migrate deploy && node dist/server.js"

Required environment variables

migrate dev vs migrate deploy

These two commands do different things. Using the wrong one in production can destroy data.

The Railway deploy command in railway.toml runs migrations automatically before starting the server — so every deploy applies any pending migrations safely:

startCommand = "npx prisma migrate deploy && node dist/server.js"
# Migrations run first, then the server starts.
# If migrations fail, the server never starts — Railway marks the deploy failed.
# The previous deploy stays live. No broken state.

A failed deploy is not an emergency — it's a normal part of shipping software. Railway keeps your previous successful deploy live while a new one is building. Nothing breaks for users. Your job is to read the logs, find the error, fix it, and redeploy.

Where to Find Logs

Common Failure Patterns

Rolling Back a Deploy

If a bad deploy makes it through and breaks production, Railway keeps your deploy history. Roll back in two clicks:

# .github/workflows/deploy-dev.yml
name: Deploy to Development

on:
  workflow_dispatch:   # Triggered manually from GitHub → Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Railway CLI
        run: npm install -g @railway/cli
      - name: Deploy backend to Development
        run: railway up --environment development --service backend
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
      - name: Deploy frontend to Development
        run: railway up --environment development --service frontend
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}