Build a Complete Project from Scratch with Claude Code

# Native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Or via npm
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

mkdir my-fullstack-app && cd my-fullstack-app
claude

# Inside the Claude Code session:
> /init

# CLAUDE.md - Project Configuration

## Project Overview
Full-stack task management app with React frontend and Python FastAPI backend.

## Tech Stack
- Frontend: React 18 + TypeScript + Vite + TailwindCSS
- Backend: Python 3.12 + FastAPI + SQLAlchemy + PostgreSQL
- Testing: Vitest (frontend), Pytest (backend)
- Deployment: Docker + docker-compose

## Common Commands
- `npm run dev` - Start frontend dev server
- `uvicorn main:app --reload` - Start backend
- `npm run test` - Frontend tests
- `pytest` - Backend tests
- `docker-compose up` - Full stack

## Architecture Decisions
- REST API with OpenAPI spec
- JWT authentication
- Repository pattern for data access
- Feature-based folder structure

## Coding Conventions
- Use absolute imports with @ prefix
- All API responses follow {data, error, meta} envelope
- Database models use snake_case, API DTOs use camelCase
- Every endpoint needs input validation with Pydantic

# Inside Claude Code session, press Shift+Tab to enter Plan Mode
> [Plan Mode] Build a task management app with:
  - User authentication (signup/login/logout)
  - CRUD operations for tasks
  - Task categories and priority levels
  - Due dates with notifications
  - REST API with OpenAPI docs

## Analysis

I'll build a full-stack task manager with the following architecture:

### Frontend (React + TypeScript)
- Pages: Login, Signup, Dashboard, TaskDetail
- Components: TaskList, TaskCard, CategoryFilter, PriorityBadge
- State: React Query for server state, Zustand for UI state

### Backend (FastAPI + PostgreSQL)
- Models: User, Task, Category
- Endpoints: /auth/*, /tasks/*, /categories/*
- Middleware: JWT auth, CORS, rate limiting

### Database Schema
- users (id, email, password_hash, created_at)
- categories (id, name, user_id, color)
- tasks (id, title, description, priority, due_date, category_id, user_id, status)

### Implementation Order (Vertical Slices)
1. Project scaffolding + Docker setup
2. Auth slice: User model → signup/login endpoints → Login UI
3. Tasks slice: Task model → CRUD endpoints → Dashboard UI
4. Categories slice: Category model → endpoints → filter UI
5. Polish: notifications, error handling, tests

Shall I proceed with this plan?

> Create the complete project structure following the approved plan. 
  Use feature-based organization for both frontend and backend.

my-fullstack-app/
├── frontend/
│   ├── src/
│   │   ├── features/
│   │   │   ├── auth/
│   │   │   │   ├── components/
│   │   │   │   ├── hooks/
│   │   │   │   ├── api.ts
│   │   │   │   └── types.ts
│   │   │   ├── tasks/
│   │   │   │   ├── components/
│   │   │   │   ├── hooks/
│   │   │   │   ├── api.ts
│   │   │   │   └── types.ts
│   │   │   └── categories/
│   │   ├── shared/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   └── utils/
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── package.json
│   └── vite.config.ts
├── backend/
│   ├── app/
│   │   ├── features/
│   │   │   ├── auth/
│   │   │   │   ├── router.py
│   │   │   │   ├── service.py
│   │   │   │   ├── models.py
│   │   │   │   └── schemas.py
│   │   │   ├── tasks/
│   │   │   └── categories/
│   │   ├── core/
│   │   │   ├── config.py
│   │   │   ├── database.py
│   │   │   └── security.py
│   │   └── main.py
│   ├── tests/
│   ├── requirements.txt
│   └── alembic/
├── docker-compose.yml
├── CLAUDE.md
└── README.md

# backend/app/features/tasks/schemas.py
from pydantic import BaseModel, Field
from datetime import datetime
from enum import Enum
from typing import Optional

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    URGENT = "urgent"

class TaskStatus(str, Enum):
    TODO = "todo"
    IN_PROGRESS = "in_progress"
    DONE = "done"

class TaskCreate(BaseModel):
    title: str = Field(..., min_length=1, max_length=200)
    description: Optional[str] = Field(None, max_length=2000)
    priority: Priority = Priority.MEDIUM
    due_date: Optional[datetime] = None
    category_id: Optional[int] = None

class TaskResponse(BaseModel):
    id: int
    title: str
    description: Optional[str]
    priority: Priority
    status: TaskStatus
    due_date: Optional[datetime]
    category_id: Optional[int]
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True

> Implement the authentication vertical slice: 
  1. User model and migration
  2. Signup and login endpoints with JWT
  3. Login and signup React pages
  Follow the schemas we designed. Use bcrypt for passwords.

# backend/app/features/auth/models.py
from sqlalchemy import Column, Integer, String, DateTime
from sqlalchemy.sql import func
from app.core.database import Base

class User(Base):
    __tablename__ = "users"
    
    id = Column(Integer, primary_key=True, index=True)
    email = Column(String(255), unique=True, index=True, nullable=False)
    password_hash = Column(String(255), nullable=False)
    created_at = Column(DateTime(timezone=True), server_default=func.now())

# backend/app/features/auth/router.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from app.core.database import get_db
from app.core.security import create_access_token, verify_password, hash_password
from .models import User
from .schemas import UserCreate, UserLogin, TokenResponse

router = APIRouter(prefix="/auth", tags=["auth"])

@router.post("/signup", response_model=TokenResponse, status_code=201)
def signup(user_data: UserCreate, db: Session = Depends(get_db)):
    existing = db.query(User).filter(User.email == user_data.email).first()
    if existing:
        raise HTTPException(status_code=409, detail="Email already registered")
    
    user = User(
        email=user_data.email,
        password_hash=hash_password(user_data.password)
    )
    db.add(user)
    db.commit()
    db.refresh(user)
    
    token = create_access_token({"sub": str(user.id)})
    return {"access_token": token, "token_type": "bearer"}

@router.post("/login", response_model=TokenResponse)
def login(credentials: UserLogin, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.email == credentials.email).first()
    if not user or not verify_password(credentials.password, user.password_hash):
        raise HTTPException(status_code=401, detail="Invalid credentials")
    
    token = create_access_token({"sub": str(user.id)})
    return {"access_token": token, "token_type": "bearer"}

// frontend/src/features/auth/components/LoginPage.tsx
import { useState } from 'react';
import { useMutation } from '@tanstack/react-query';
import { useNavigate } from 'react-router-dom';
import { authApi } from '../api';
import { useAuthStore } from '../../../shared/stores/authStore';

export function LoginPage() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const navigate = useNavigate();
  const setToken = useAuthStore((s) => s.setToken);

  const loginMutation = useMutation({
    mutationFn: authApi.login,
    onSuccess: (data) => {
      setToken(data.access_token);
      navigate('/dashboard');
    },
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    loginMutation.mutate({ email, password });
  };

  return (
    <div className="min-h-screen flex items-center justify-center">
      <form onSubmit={handleSubmit} className="w-full max-w-md space-y-4 p-8">
        <h1 className="text-2xl font-bold text-center">Log In</h1>
        
        {loginMutation.isError && (
          <div className="bg-red-50 text-red-600 p-3 rounded">
            Invalid email or password
          </div>
        )}
        
        <input
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          placeholder="Email"
          className="w-full p-3 border rounded"
          required
        />
        <input
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          placeholder="Password"
          className="w-full p-3 border rounded"
          required
        />
        <button
          type="submit"
          disabled={loginMutation.isPending}
          className="w-full p-3 bg-blue-600 text-white rounded hover:bg-blue-700"
        >
          {loginMutation.isPending ? 'Logging in...' : 'Log In'}
        </button>
      </form>
    </div>
  );
}

# In Claude Code settings or via flag
> /config auto-accept true

# Now Claude will create files, install packages, and run commands
# without asking for approval at each step

> /agents create frontend-agent "Implement the TaskList and TaskCard 
  components following our design system. Use the task API types from 
  features/tasks/types.ts."

> /agents create backend-agent "Implement the tasks CRUD endpoints 
  following the repository pattern. Include pagination and filtering."

> Generate comprehensive tests for the auth feature:
  - Unit tests for password hashing and JWT creation
  - Integration tests for signup and login endpoints
  - Frontend component tests for LoginPage

# backend/tests/features/auth/test_auth_endpoints.py
import pytest
from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

class TestSignup:
    def test_successful_signup(self, db_session):
        response = client.post("/auth/signup", json={
            "email": "test@example.com",
            "password": "SecurePass123!"
        })
        assert response.status_code == 201
        data = response.json()
        assert "access_token" in data
        assert data["token_type"] == "bearer"
    
    def test_duplicate_email_returns_409(self, db_session, existing_user):
        response = client.post("/auth/signup", json={
            "email": existing_user.email,
            "password": "AnotherPass456!"
        })
        assert response.status_code == 409
        assert "already registered" in response.json()["detail"]
    
    def test_weak_password_rejected(self, db_session):
        response = client.post("/auth/signup", json={
            "email": "new@example.com",
            "password": "123"
        })
        assert response.status_code == 422

class TestLogin:
    def test_successful_login(self, db_session, existing_user):
        response = client.post("/auth/login", json={
            "email": "existing@example.com",
            "password": "ExistingPass123!"
        })
        assert response.status_code == 200
        assert "access_token" in response.json()

    def test_wrong_password_returns_401(self, db_session, existing_user):
        response = client.post("/auth/login", json={
            "email": "existing@example.com",
            "password": "WrongPassword!"
        })
        assert response.status_code == 401
    
    def test_nonexistent_email_returns_401(self, db_session):
        response = client.post("/auth/login", json={
            "email": "nobody@example.com",
            "password": "SomePass123!"
        })
        assert response.status_code == 401

// frontend/src/features/auth/components/__tests__/LoginPage.test.tsx
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { MemoryRouter } from 'react-router-dom';
import { LoginPage } from '../LoginPage';
import { vi } from 'vitest';

const queryClient = new QueryClient({
  defaultOptions: { queries: { retry: false } }
});

const wrapper = ({ children }: { children: React.ReactNode }) => (
  <QueryClientProvider client={queryClient}>
    <MemoryRouter>{children}</MemoryRouter>
  </QueryClientProvider>
);

describe('LoginPage', () => {
  it('renders login form with email and password fields', () => {
    render(<LoginPage />, { wrapper });
    expect(screen.getByPlaceholderText('Email')).toBeInTheDocument();
    expect(screen.getByPlaceholderText('Password')).toBeInTheDocument();
    expect(screen.getByRole('button', { name: /log in/i })).toBeInTheDocument();
  });

  it('shows loading state during submission', async () => {
    render(<LoginPage />, { wrapper });
    fireEvent.change(screen.getByPlaceholderText('Email'), {
      target: { value: 'test@test.com' }
    });
    fireEvent.change(screen.getByPlaceholderText('Password'), {
      target: { value: 'password123' }
    });
    fireEvent.click(screen.getByRole('button'));
    
    await waitFor(() => {
      expect(screen.getByText('Logging in...')).toBeInTheDocument();
    });
  });

  it('displays error message on failed login', async () => {
    // Mock failed API response
    vi.spyOn(global, 'fetch').mockRejectedValueOnce(new Error('401'));
    
    render(<LoginPage />, { wrapper });
    fireEvent.click(screen.getByRole('button'));
    
    await waitFor(() => {
      expect(screen.getByText(/invalid email or password/i)).toBeInTheDocument();
    });
  });
});

> The login endpoint returns 500 instead of 401 when the password is wrong.
  Here's the error: "AttributeError: 'NoneType' object has no attribute 'password_hash'"

> Review the entire tasks feature for:
  - Security vulnerabilities
  - Performance issues
  - Code consistency with our conventions
  - Missing error handling

## Code Review: Tasks Feature

### Security Issues (High Priority)
1. **SQL Injection Risk** in task search:
   - File: backend/app/features/tasks/service.py:45
   - Issue: f-string used in query filter
   - Fix: Use SQLAlchemy's parameterized queries

2. **Missing authorization check**:
   - File: backend/app/features/tasks/router.py:67
   - Issue: DELETE /tasks/{id} doesn't verify task ownership
   - Fix: Add user_id check before deletion

### Performance Issues (Medium Priority)
3. **N+1 query** in task listing:
   - File: backend/app/features/tasks/router.py:23
   - Issue: Category loaded separately for each task
   - Fix: Use joinedload() in the query

### Convention Violations (Low Priority)
4. TaskCard component uses inline styles instead of Tailwind classes
5. API error responses don't follow {data, error, meta} envelope

Shall I fix these issues?

> Fix all security issues identified in the review. 
  Maintain existing test coverage—update tests if interfaces change.

> Create production Docker setup with:
  - Multi-stage builds for minimal image size
  - Docker Compose for local development
  - Environment variable configuration
  - Health check endpoints

# docker-compose.yml
version: "3.9"

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${DB_USER:-taskapp}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-localdev}
      POSTGRES_DB: ${DB_NAME:-taskapp}
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U taskapp"]
      interval: 5s
      timeout: 3s
      retries: 5

  backend:
    build:
      context: ./backend
      target: development
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://${DB_USER:-taskapp}:${DB_PASSWORD:-localdev}@db:5432/${DB_NAME:-taskapp}
      JWT_SECRET: ${JWT_SECRET:-dev-secret-change-in-prod}
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - ./backend:/app

  frontend:
    build:
      context: ./frontend
      target: development
    ports:
      - "5173:5173"
    environment:
      VITE_API_URL: http://localhost:8000
    volumes:
      - ./frontend:/app
      - /app/node_modules

volumes:
  pgdata:

> Create a GitHub Actions CI pipeline that:
  - Runs backend tests with a PostgreSQL service container
  - Runs frontend tests  
  - Builds Docker images
  - Only deploys on main branch