Building a Full-Stack Web Project with Claude Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

focusboard/
├── apps/
│   └── web/                    # Next.js app (UI + API routes)
├── packages/
│   ├── db/                     # Drizzle schema, migrations, queries
│   ├── api/                    # tRPC routers (the contract layer)
│   ├── ui/                     # shadcn components + custom
│   └── shared/                 # Zod schemas, enums, utility types
├── docs/
│   ├── ARCHITECTURE.md         # System overview (~1 page)
│   ├── DECISIONS.md            # ADR log
│   ├── CONVENTIONS.md          # Naming, error handling, patterns
│   └── features/               # One file per feature
│       ├── auth.md
│       ├── boards.md
│       └── ...
├── CLAUDE.md                   # Root instructions for Claude
├── .github/workflows/ci.yml
└── turbo.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

You're seeing FocusBoard, a brand-new monorepo. Read package.json,
turbo.json, the tsconfig files, and the directory structure. Then
write CLAUDE.md at the root.

Include:
- Stack summary (one paragraph)
- Common commands (pnpm dev, pnpm test, pnpm db:migrate)
- Where things live (apps/, packages/, docs/)
- Hard rules: "always run pnpm typecheck after backend changes",
  "never edit packages/db/migrations — generate via pnpm db:generate"
- Pointer: "Before working on a feature, read docs/features/<name>.md
  if it exists, plus docs/CONVENTIONS.md."

Keep it under 80 lines. No fluff.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# FocusBoard Architecture

## Data flow
Browser → Next.js Server Action / tRPC → Drizzle → Postgres
                                       ↘ Pusher → other browsers

## Auth boundary
Auth.js session middleware runs in apps/web/middleware.ts.
Every tRPC procedure resolves `ctx.user` or throws UNAUTHORIZED.

## Module dependencies
ui      → shared
api     → db, shared
db      → shared
web     → api, ui, db (read-only types)

ESLint enforces: ui MUST NOT import from db or api.

1
2
3
4

## ADR-001: tRPC over REST  (2026-01-15)
Chose tRPC because end-to-end types make Claude-driven changes safer.
Trade-off: harder to consume from non-TS clients. Acceptable — no
mobile/3rd-party plans for v1.

1
2
3
4
5

# .github/workflows/ci.yml
- run: pnpm typecheck
- run: pnpm lint
- run: pnpm test
- run: pnpm build

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

We're building auth for FocusBoard. Read:
- CLAUDE.md
- docs/ARCHITECTURE.md
- docs/CONVENTIONS.md
- packages/db/src/schema.ts (currently empty)
- apps/web/src/app/layout.tsx

Then propose a plan in plan mode. Requirements:
- Email + password signup/login
- Auth.js v5 with credentials provider
- Drizzle adapter
- Zod validation on all inputs
- Session via JWT (cookie)
- A /login page and /signup page using shadcn forms
- Tests: at minimum, signup → login → access /app/dashboard

Stop at the plan. Don't write code yet.

1
2
3

Approved. Implement. After each file, run pnpm typecheck.
Update docs/features/auth.md as you go — schema, routes, edge
cases, and one paragraph of "what to know if you ever touch this."

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Read docs/features/auth.md and packages/db/src/schema/users.ts.
We're adding workspaces. Each user can create a workspace and
invite others by email.

Design (read first, don't code):
- packages/db/src/schema/workspaces.ts
- packages/api/src/routers/workspaces.ts (tRPC)
- packages/shared/src/validators/workspace.ts (Zod)

Constraints from CONVENTIONS.md still apply. Use procedure types
already established in api/src/trpc.ts (auth, public).

Plan first.

1
2
3
4

Read docs/features/auth.md, docs/features/workspaces.md, and
apps/web/src/components/forms/ (the existing form patterns).
Build the /app/new-workspace page using the same form pattern as
signup. Wire to api.workspaces.create.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

Read docs/ARCHITECTURE.md, docs/CONVENTIONS.md, and
docs/features/workspaces.md.

Design the data model and tRPC contract for boards. Do NOT
implement. Produce three files:

1. packages/db/src/schema/boards.ts (boards, columns, cards tables)
2. packages/shared/src/validators/board.ts (Zod input schemas)
3. packages/api/src/routers/boards.ts — but ONLY the procedure
   signatures with `.query()`/`.mutation()` and `// TODO` bodies.

Then write docs/features/boards.md describing:
- The data model
- Each procedure's contract (inputs, outputs, errors, auth rules)
- Open questions

Constraints:
- Boards belong to a workspace
- Columns are ordered (use fractional indexing — establish a
  helper in packages/shared/src/lib/ordering.ts if missing)
- Cards belong to a column, also fractionally ordered
- Soft delete only (deletedAt column)

1
2
3
4
5
6

Read docs/features/boards.md and the three files from the
contract session. Implement the tRPC procedures. Write Vitest
tests for each — include auth checks and ordering correctness.

Don't touch the frontend. Don't change the schema unless the
contract is impossible (and if so, stop and explain).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Read:
- docs/features/boards.md
- packages/api/src/routers/boards.ts (already implemented)
- apps/web/src/app/(app)/dashboard/page.tsx (existing pattern)
- apps/web/src/components/ui/ (shadcn primitives — list only, don't expand)

Build the board view at /app/w/[workspaceId]/b/[boardId].
Use @dnd-kit for drag/drop. Optimistic updates via tRPC's
useMutation onMutate.

Stop after the happy path works. We'll add polish in a follow-up.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Real-time integration

Pusher channel per workspace: `workspace-${id}`.

Mutations that broadcast (must call `broadcast()` helper):

| Procedure                  | Event           | Payload     |
|----------------------------|-----------------|-------------|
| boards.create              | board:created   | Board       |
| cards.move                 | card:moved      | {id, col}   |
| cards.update               | card:updated    | Card        |
| comments.create            | comment:added   | Comment     |
| timer.start / timer.stop   | timer:changed   | TimerEvent  |

Subscribers: useWorkspaceEvents() hook in apps/web/src/lib/realtime.

1
2
3
4
5
6

Read docs/features/realtime.md.
Step 1: Add the broadcast() helper in packages/api/src/lib/pusher.ts.
Step 2: Wire it into the procedures listed in the table above.
For each: read the procedure file, add the broadcast call, run tests.

Show me the diff before moving to step 2.

1
2
3
4
5

Read CLAUDE.md, docs/CONVENTIONS.md, and docs/features/*.md.
Then list 10-20 files at random under packages/api/src/routers/.

For each, check: does it follow the conventions? Are docs current?
Report a punch list. Don't fix anything yet.

1
2
3
4
5
6

Read docs/features/cards.md and packages/db/src/schema/boards.ts.
We're adding labels: each card has 0..N labels. Labels belong to
a board (not a workspace). Color + name. Only board members can
manage labels.

What's the smallest schema change? Plan only.

1
2

Approved. Implement schema + migration first. Stop after
pnpm db:generate succeeds.

1
2
3

Now add tRPC procedures: labels.list, labels.create, labels.update,
labels.delete, cards.attachLabel, cards.detachLabel. Update
docs/features/cards.md.

1
2
3
4

Read the LabelChip pattern in packages/ui/src/badge.tsx if it exists,
otherwise design one. Add label management to the card detail
modal — apps/web/src/components/card-detail.tsx. Don't touch
anything else in that file.

1
2

Write a Playwright test: create label, attach to card, refresh,
label still shown.

1
2

Run pnpm typecheck, lint, test. If green, draft a commit message
in conventional commits style.