Fullstack Build Playbook

End-to-end guide to build a feature across backend + frontend using existing project skills.

Purpose

Aligns work across BE and FE so features are built consistently and safely.

Required Skills (Read First)

• •.claude/skills/task-commands/SKILL.md
• •.claude/skills/api-generator/SKILL.md
• •.claude/skills/backend-logging/SKILL.md
• •.claude/skills/frontend-module/SKILL.md
• •.claude/skills/frontend-design/SKILL.md
• •.claude/skills/namespace-aliases/SKILL.md
• •.claude/skills/task-distribution/SKILL.md
• •.claude/skills/e2e-selectors/SKILL.md
• •.claude/skills/mermaid-diagrams/SKILL.md

Build Flow (Senior Fullstack)

flowchart TD
    A[1. Understand Domain] --> B{Need API?}
    B -->|Yes| C[2. Generate API<br/>npm run gen]
    B -->|No| D[3. Backend<br/>services + repos]
    C --> D
    D --> E[4. Frontend<br/>components + hooks]
    E --> F[5. Tests<br/>integration + E2E]
    F --> G[6. Verify<br/>lint + build]

1) Understand the Domain

• •Read the epic in docs/epics/<epic>.md.
• •Identify entities, workflows, and critical user actions.
• •Decide if new API endpoints are required.

2) Decide API Generation

Use .claude/skills/task-distribution/SKILL.md to decide if npm run gen -- <pkg> is required.

Generate when:

• •New endpoints needed
• •Proto exists and generated files missing/outdated

Skip when:

• •UI-only changes
• •Styling-only changes

3) Backend Implementation

If new API:

• •Create/Update bff/<pkg>/<pkg>.proto
• •Run npm run gen -- <pkg>

Then implement services and repos:

• •be/core/services/<pkg>.service.ts
• •be/core/repo/<pkg>.repo.ts

Rules:

• •Use @Ciri/* aliases
• •Use UnitLogger / GeneralLogger (no console.log)
• •Routes are generated; do not edit them

4) Frontend Implementation

Module structure:

fe/src/components/<module>/
├── Main<Module>.tsx
├── Create<Module>Dialog.tsx
├── store.ts
└── utils.ts (optional)

State strategy:

• •Server data → TanStack Query (generated hooks)
• •Module UI state → Zustand
• •Global app state → Redux

Design rules:

• •Follow .claude/skills/frontend-design/SKILL.md
• •All colors require dark: variants
• •Use core-design components

Selectors:

• •Add stable data-* attributes for E2E

5) Testing

Backend:

• •Add integration tests in be/test/<module>/
• •Run cd be && bunx vitest run

E2E:

• •User runs Playwright (task e2e) if required

6) Verification

• •task lint
• •cd be && bun run build
• •cd fe && npm run build

Common Pitfalls

• •Editing generated routes or hooks (never do)
• •Using CSS classes or text for E2E selectors
• •Missing dark mode colors
• •Using React useState for complex module state (use Zustand)

Quick Checklist

• • Epic understood and scoped
• • API generation decision made
• • Services + repos implemented
• • UI built with correct design system
• • E2E selectors added
• • BE integration tests added
• • Lint + build pass