Playbook Full Stack

Web App Creation Playbook

End-to-end workflow for creating new web applications. From initial planning through deployment and monitoring.

# agent_prompt

Copy this prompt when starting a new web app project:

"I'm building a new web app. Help me follow this workflow:

1. Define requirements and user stories

2. Choose tech stack based on requirements

3. Set up project structure and tooling

4. Build data models and API first

5. Implement UI components

6. Add authentication and authorization

7. Write tests as we go

8. Deploy with CI/CD pipeline"

Planning & Requirements

Before writing code, understand what you're building and why.

Questions to Answer

• Who are the users? Define personas and use cases
• What problem does it solve? Core value proposition
• What are the must-haves vs nice-to-haves? MVP scope
• What are the constraints? Timeline, budget, team size
• What's the success metric? How will you know it works?

User Story Format

As a [type of user]
I want to [action]
So that [benefit]

Example:
As a project manager
I want to see all tasks assigned to my team
So that I can track progress and identify blockers

Tech Stack Selection

Choose technologies based on requirements, not trends.

Simple App / Landing Page

• Framework: Astro, Next.js, or plain HTML
• Styling: Tailwind CSS
• Hosting: Vercel, Netlify, Cloudflare Pages
• Database: None or SQLite

Full-Stack App

• Framework: Next.js, SvelteKit, Remix
• Database: PostgreSQL, SQLite
• ORM: Prisma, Drizzle
• Auth: NextAuth, Lucia, Clerk

Decision Factors

• Team expertise: Use what your team knows
• Time to market: Frameworks with batteries included
• Scale requirements: Start simple, scale later
• Hosting costs: Consider serverless vs VPS

Project Setup

Establish structure and tooling before writing features.

Standard Project Structure

project/
├── src/
│   ├── components/     # Reusable UI components
│   ├── pages/          # Route pages
│   ├── lib/            # Utilities, helpers
│   ├── api/            # API routes/handlers
│   ├── hooks/          # Custom hooks (React)
│   └── styles/         # Global styles
├── public/             # Static assets
├── tests/              # Test files
├── .env.example        # Environment template
├── .gitignore
├── package.json
└── README.md

Essential Tooling

• Linting: ESLint with recommended rules
• Formatting: Prettier for consistent style
• Type checking: TypeScript (recommended)
• Git hooks: Husky + lint-staged
• Testing: Vitest or Jest

Data Layer & API

Build the foundation before the UI. Data model drives everything.

Database Schema First

// Define your data models (Prisma example)
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String
}

API Design Principles

• RESTful conventions: GET /users, POST /users, GET /users/:id
• Consistent responses: { data, error, meta }
• Validation: Validate all inputs (Zod recommended)
• Error handling: Meaningful error messages and codes

UI Implementation

Build components bottom-up, pages top-down.

Component Order

Design tokens (colors, spacing, typography)
Atomic components (Button, Input, Card)
Composite components (Form, Modal, Navbar)
Page layouts (Header, Sidebar, Footer)
Feature components (UserList, PostEditor)
Full pages (Dashboard, Settings)

State Management

• Local state: useState for component-specific state
• Server state: TanStack Query or SWR for API data
• Global state: Zustand or Context (avoid Redux unless needed)
• URL state: Use query params for shareable state

Authentication & Authorization

Don't build auth from scratch. Use battle-tested solutions.

Auth Options

• NextAuth.js: Flexible, many providers
• Lucia: Lightweight, full control
• Clerk: Managed, quick setup
• Supabase Auth: If using Supabase

Authorization Pattern

// Middleware check
if (!session) redirect('/login');
if (!hasPermission(user, 'admin')) {
  return { error: 'Forbidden' };
}

Testing Strategy

Write tests as you build, not after. Focus on critical paths.

Testing Pyramid

        /\
       /  \     E2E (10%) - Critical user journeys
      /----\
     /      \   Integration (20%) - API, components
    /--------\
   /          \ Unit (70%) - Functions, utilities
  --------------

• Unit tests: Pure functions, utilities, hooks
• Integration: API routes, component interactions
• E2E: Login flow, checkout, critical paths (Playwright)

Deployment & CI/CD

Automate deployment from day one. Push to main = deploy.

CI/CD Pipeline

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

      - name: Deploy
        run: # Deploy to your platform

Hosting Options

• Vercel: Best for Next.js
• Netlify: Great for static/Jamstack
• Railway: Full-stack apps
• Fly.io: Docker-based apps
• VPS: Full control (Hetzner, DO)

Pre-Launch Checklist

☐ Environment variables set
☐ Database migrated
☐ SSL certificate active
☐ Error monitoring (Sentry)
☐ Analytics installed
☐ Backup strategy in place

# quick_reference

Recommended Stack (2024)

• Framework: Next.js 14+ or Astro
• Styling: Tailwind CSS
• Database: PostgreSQL + Prisma
• Auth: NextAuth.js or Lucia
• Validation: Zod
• Testing: Vitest + Playwright

Common Mistakes

• Building before planning
• Over-engineering the MVP
• Skipping auth library (DIY)
• No error handling
• Manual deployments
• No monitoring/logging