NEW ENGINEER ONBOARDING GUIDE - Next.js Project

DAY 1: LOCAL SETUP

PREREQUISITES
→ Node 18+, pnpm (not npm), VS Code
→ GitHub access (fork + upstream configured)
→ Figma viewer access (design system link)

SETUP STEPS (30 min total)
1. git clone (fork) → cd project
2. pnpm install (handles dependencies)
3. cp .env.example .env.local (copy env template)
4. pnpm dev (starts http://localhost:3000)
5. pnpm test (verify all tests pass)

CODEBASE ARCHITECTURE MAP
project/
├── app/                 (Next.js app router routes)
│   ├── (dashboard)/      (authenticated routes)
│   ├── (marketing)/      (public landing pages)
│   ├── api/              (API endpoints)
│   └── layout.tsx        (root layout)
├── components/          (React component library)
│   ├── UI/               (buttons, forms, cards)
│   ├── Features/         (feature-specific components)
│   └── *.stories.tsx     (Storybook examples)
├── lib/                 (utilities, helpers, types)
│   ├── db.ts            (database client)
│   ├── auth.ts          (auth middleware)
│   └── api-client.ts    (fetch wrapper)
├── public/              (static assets, logos)
├── prisma/              (database schema + migrations)
└── tests/               (unit + integration tests)

KEY PATTERNS YOU'LL SEE

DATA FETCHING (Server Components)
// app/posts/page.tsx
const Posts = async () => {
  const posts = await db.post.findMany();
  return <PostList items={posts} />;
};
→ Rationale: Data fetches run server-side, no client overhead

FORM HANDLING (Server Actions)
'use server'
export async function createPost(formData) {
  const data = new FormData(formData);
  await db.post.create({...});
  revalidatePath('/posts');
}
→ Rationale: No API route needed, form submission direct

STYLING
→ Tailwind CSS for components
→ CSS modules for page-specific overrides
→ Design tokens in tailwind.config.js

DAY 1-2 GETTING UNBLOCKED

COMMON ISSUE: Port 3000 already in use
→ Solution: lsof -i :3000 | kill -9 <PID> OR pnpm dev -p 3001

COMMON ISSUE: Prisma migrations failing
→ Solution: Check .env.local DATABASE_URL (must point to development DB)
→ Run: pnpm prisma migrate dev

SLACK CHANNEL: #engineering (ask here, veterans monitor)
PAIR BUDDY: (assigned person, 30 min introduction call)

FIRST TASK: Pick from 'Good First Issue' label on GitHub
→ Expected: 2-4 hours to complete
→ Expected: 1-2 code review rounds before merge

WEEK 2 MILESTONES
→ Deployed one small feature end-to-end
→ Attended architecture sync (Friday 10am)
→ Added one test to existing suite
→ Read: CONTRIBUTING.md + architecture decision log