Bolt.new Context Setup: Build Full-Stack Apps That Actually Work

# Application Architecture Template

## Application Overview
**Name**: [Your App Name]
**Type**: [SaaS Platform / E-commerce / CRM / Portfolio / etc.]
**Target Users**: [Specific user personas and use cases]
**Core Value Proposition**: [What problem this solves]

## Technical Stack Requirements
**Frontend**: 
- Framework: Next.js 14 with App Router
- Styling: Tailwind CSS with custom design system
- State Management: Zustand for global state, React Query for server state
- Forms: React Hook Form with Zod validation

**Backend**:
- Runtime: Node.js with Express.js
- Database: PostgreSQL with Prisma ORM
- Authentication: NextAuth.js with JWT tokens
- File Storage: AWS S3 or Cloudinary
- Email: Resend or SendGrid

**Deployment**:
- Platform: Vercel for frontend, Railway for database
- Environment Management: Separate dev/staging/production
- Domain: Custom domain with SSL
- Monitoring: Basic error tracking and analytics

## Data Architecture
**Primary Entities**:
- Users (authentication, profiles, preferences)
- [Your main business entities - projects, orders, posts, etc.]
- System entities (audit logs, settings, notifications)

**Key Relationships**:
- User has many [entities]
- [Entity] belongs to User
- [Complex relationships specific to your domain]

**Data Validation**:
- Client-side validation with Zod schemas
- Server-side validation and sanitization
- Database constraints and indexes

# Feature Specification Template

## Core Features (Must-Have)

### 1. User Authentication System
**Requirements**:
- Email/password registration with email verification
- Login with "remember me" option
- Password reset flow with secure token
- User profile management (name, avatar, preferences)

**Technical Details**:
- Use NextAuth.js with credentials provider
- Hash passwords with bcrypt (minimum 12 rounds)
- JWT tokens with 7-day expiration, refresh token pattern
- Email verification required before account activation

**User Stories**:
- As a new user, I can create an account with my email
- As a user, I can log in and stay logged in for a week
- As a user, I can reset my password if I forget it
- As a user, I can update my profile information

### 2. [Your Main Feature]
**Requirements**:
[Detailed requirements for your primary feature]

**API Endpoints**:
- GET /api/[resource] - List with pagination and filtering
- POST /api/[resource] - Create with validation
- PUT /api/[resource]/[id] - Update with optimistic locking
- DELETE /api/[resource]/[id] - Soft delete with audit trail

**Data Validation**:
```typescript
// Zod schema for your main entity
const [EntitySchema] = z.object({
  title: z.string().min(1).max(100),
  description: z.string().optional(),
  status: z.enum(['draft', 'published', 'archived']),
  createdAt: z.date(),
  updatedAt: z.date(),
  userId: z.string().uuid(),
});
```

**User Experience**:
- Loading states for all async operations
- Optimistic updates where appropriate
- Error handling with user-friendly messages
- Keyboard shortcuts for power users

## Advanced Features (Nice-to-Have)

### 1. Real-time Updates
- WebSocket connection for live data updates
- Optimistic UI updates with conflict resolution
- Offline support with sync when reconnected

### 2. Advanced Search and Filtering
- Full-text search with PostgreSQL text search
- Multiple filter combinations
- Saved searches and bookmarks
- Export functionality

### 3. Team Collaboration
- User roles and permissions
- Shared workspaces
- Activity feeds and notifications
- Comment system with mentions

# Production Quality Requirements

## Security Requirements
**Authentication & Authorization**:
- All API endpoints require authentication except public routes
- Role-based access control (RBAC) for admin functions
- Rate limiting on authentication endpoints (5 attempts/minute)
- CSRF protection for state-changing operations

**Data Security**:
- Input validation and sanitization on all user data
- SQL injection prevention (use parameterized queries)
- XSS prevention (escape all user content)
- Secure headers (CSP, HSTS, X-Frame-Options)

**API Security**:
```typescript
// Example secure API route
import { rateLimit } from 'express-rate-limit';
import { body, validationResult } from 'express-validator';
import { authenticateToken } from '../middleware/auth';

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per windowMs
});

app.post('/api/[resource]', 
  limiter,
  authenticateToken,
  [
    body('title').isLength({ min: 1, max: 100 }).escape(),
    body('description').optional().isLength({ max: 1000 }).escape()
  ],
  async (req, res) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }
    
    try {
      // Secure database operation
      const result = await createResource(req.body, req.userId);
      res.json(result);
    } catch (error) {
      console.error('Resource creation error:', error);
      res.status(500).json({ error: 'Internal server error' });
    }
  }
);
```

## Performance Requirements
**Frontend Performance**:
- Initial page load under 2 seconds
- Time to Interactive under 3 seconds
- Bundle size under 250KB (gzipped)
- Image optimization and lazy loading

**Backend Performance**:
- API response times under 500ms for simple queries
- Database connection pooling (max 10 connections)
- Proper database indexing on query columns
- Caching strategy for frequently accessed data

**Database Optimization**:
```sql
-- Example indexes for common queries
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_resources_user_id ON resources(user_id);
CREATE INDEX idx_resources_created_at ON resources(created_at DESC);
CREATE INDEX idx_resources_status ON resources(status);
```

## Error Handling Strategy
**Client-Side Error Handling**:
- Global error boundary for React components
- Toast notifications for user-facing errors
- Retry logic for network failures
- Graceful degradation for non-critical features

**Server-Side Error Handling**:
- Global error handler middleware
- Structured error logging
- Health check endpoints
- Database connection error recovery

```typescript
// Global error handler
app.use((error: Error, req: Request, res: Response, next: NextFunction) => {
  console.error('Unhandled error:', error);
  
  // Don't leak error details in production
  const message = process.env.NODE_ENV === 'production' 
    ? 'Internal server error' 
    : error.message;
    
  res.status(500).json({ error: message });
});
```

## Testing Strategy
**Unit Testing**:
- Test all utility functions and business logic
- API route testing with mocked database
- Component testing for critical user interactions

**Integration Testing**:
- Database operations with test database
- API endpoint testing with real HTTP requests
- Authentication flow testing

**End-to-End Testing**:
- Critical user journeys (registration, login, main features)
- Cross-browser compatibility testing
- Mobile responsiveness testing

# Production Bolt Prompt Template

Build a [Application Type] called [App Name] with the following specifications:

## Application Overview
I need a full-stack [SaaS platform/e-commerce site/CRM/etc.] that [specific problem it solves]. This should be production-ready code that I can deploy and use with real users.

## Technical Requirements
- **Frontend**: Next.js 14 with TypeScript, Tailwind CSS, React Hook Form
- **Backend**: Node.js API routes with Prisma ORM and PostgreSQL
- **Authentication**: NextAuth.js with email/password and email verification
- **File Upload**: Cloudinary integration for image handling
- **Payments**: Stripe integration for subscriptions (if applicable)
- **Email**: Resend for transactional emails

## Core Features
1. **User Authentication**
   - Registration with email verification
   - Login/logout with session management
   - Password reset functionality
   - User profile management with avatar upload

2. **[Your Main Feature]**
   - [Detailed requirements for primary functionality]
   - CRUD operations with proper validation
   - Real-time updates where appropriate
   - Search and filtering capabilities

3. **Dashboard and Analytics**
   - User dashboard with key metrics
   - Data visualization with charts
   - Export functionality
   - Activity logging

## Data Models
Define these database models with proper relationships:

```typescript
// User model
model User {
  id          String   @id @default(cuid())
  email       String   @unique
  name        String?
  avatar      String?
  verified    Boolean  @default(false)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  
  // Your app-specific relationships
  [resources] [Resource][]
}

// Your main business model
model [Resource] {
  id          String   @id @default(cuid())
  title       String
  description String?
  status      String   @default("draft")
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  
  userId      String
  user        User     @relation(fields: [userId], references: [id])
}
```

## Security and Validation
- Implement proper input validation using Zod schemas
- Add rate limiting to authentication endpoints
- Use CSRF protection for forms
- Sanitize all user inputs
- Implement proper error handling without leaking sensitive information

## User Experience Requirements
- Responsive design that works on mobile, tablet, and desktop
- Loading states for all async operations
- Toast notifications for user feedback
- Optimistic UI updates where appropriate
- Proper error messages and empty states
- Keyboard accessibility and screen reader support

## Deployment Setup
- Configure for Vercel deployment with environment variables
- Set up database connection with connection pooling
- Include proper TypeScript configuration
- Add basic SEO meta tags and sitemap
- Configure CORS and security headers

## Success Criteria
The application should:
- Handle 100+ concurrent users
- Load pages in under 2 seconds
- Work offline for read operations
- Pass WCAG 2.1 accessibility standards
- Handle edge cases gracefully
- Be ready for production deployment

Please build this step by step, ensuring each feature is fully functional before moving to the next.

# Enhancement Prompt Examples

## Database Optimization
"Optimize the database schema and queries for the current application:

1. Add proper indexes for all query patterns
2. Implement database connection pooling
3. Add audit logging for important user actions
4. Set up database backups and migration strategy
5. Add performance monitoring for slow queries

Include the SQL migration scripts and updated Prisma schema."

## Authentication Enhancement
"Enhance the authentication system with production features:

1. Add two-factor authentication using TOTP
2. Implement social login (Google, GitHub)
3. Add session management with refresh tokens
4. Implement account lockout after failed attempts
5. Add admin user management functionality
6. Include audit trail for authentication events

Update all related API routes and UI components."

## Real-time Features
"Add real-time functionality to the application:

1. Set up WebSocket connection with Socket.io
2. Implement real-time updates for [specific features]
3. Add presence indicators (who's online)
4. Implement real-time notifications
5. Add collaborative editing capabilities
6. Handle connection loss and reconnection gracefully

Include both client and server-side implementations."

## Payment Integration
"Integrate Stripe payment processing:

1. Set up Stripe webhook handling
2. Implement subscription management
3. Add usage-based billing
4. Create billing dashboard for users
5. Handle payment failures and retries
6. Add invoice generation and download
7. Implement proration for plan changes

Include complete checkout flow and subscription management."

## Advanced Search
"Implement advanced search and filtering:

1. Add full-text search with PostgreSQL text search
2. Implement faceted search with multiple filters
3. Add search suggestions and autocomplete
4. Create saved searches functionality
5. Add search analytics and popular searches
6. Implement search result highlighting
7. Add export functionality for search results

Include search UI with proper performance optimization."

# Environment Configuration

## .env.example Template
```bash
# Database
DATABASE_URL="postgresql://username:password@localhost:5432/myapp"
DIRECT_URL="postgresql://username:password@localhost:5432/myapp"

# Authentication
NEXTAUTH_SECRET="your-secret-key-here"
NEXTAUTH_URL="http://localhost:3000"

# Email Service
RESEND_API_KEY="your-resend-api-key"
FROM_EMAIL="[email protected]"

# File Upload
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"

# Payment Processing (if applicable)
STRIPE_PUBLIC_KEY="pk_test_..."
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# External APIs
[YOUR_API_NAME]_API_KEY="your-api-key"

# Environment
NODE_ENV="development"
```

## Vercel Deployment Configuration
```json
{
  "framework": "nextjs",
  "buildCommand": "prisma generate && next build",
  "installCommand": "npm ci",
  "env": {
    "DATABASE_URL": "@database_url",
    "NEXTAUTH_SECRET": "@nextauth_secret",
    "NEXTAUTH_URL": "@nextauth_url"
  },
  "functions": {
    "app/api/cron/**": {
      "maxDuration": 300
    }
  },
  "rewrites": [
    {
      "source": "/healthcheck",
      "destination": "/api/health"
    }
  ]
}
```

## Database Migration Strategy
```bash
# Development workflow
npm run db:migrate:dev    # Create and apply migration
npm run db:seed          # Seed development data
npm run db:studio        # Open Prisma Studio

# Production workflow  
npm run db:migrate:deploy # Apply migrations in production
npm run db:backup        # Backup before major changes
```

# Performance Optimization Guide

## Frontend Optimization
```typescript
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    optimizePackageImports: ['lucide-react', '@headlessui/react'],
  },
  images: {
    domains: ['res.cloudinary.com'],
    formats: ['image/webp', 'image/avif'],
  },
  webpack: (config, { dev }) => {
    if (!dev) {
      // Production optimizations
      config.optimization.splitChunks = {
        chunks: 'all',
        cacheGroups: {
          vendor: {
            test: /[\\/]node_modules[\\/]/,
            name: 'vendors',
            chunks: 'all',
          },
        },
      };
    }
    return config;
  },
};

module.exports = nextConfig;
```

## Database Connection Optimization
```typescript
// lib/prisma.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma = globalForPrisma.prisma ?? new PrismaClient({
  log: process.env.NODE_ENV === 'development' ? ['query'] : [],
  datasources: {
    db: {
      url: process.env.DATABASE_URL,
    },
  },
});

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma;
}

// Connection pooling
export const db = prisma.$extends({
  query: {
    $allModels: {
      async findMany({ args, query }) {
        // Add automatic pagination limit
        if (!args.take) {
          args.take = 50;
        }
        return query(args);
      },
    },
  },
});
```

## API Route Optimization
```typescript
// Example optimized API route
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { rateLimit } from '@/lib/rate-limit';
import { auth } from '@/lib/auth';
import { db } from '@/lib/prisma';

const limiter = rateLimit({
  interval: 60 * 1000, // 1 minute
  uniqueTokenPerInterval: 500, // Max 500 users per second
});

const createSchema = z.object({
  title: z.string().min(1).max(100),
  description: z.string().optional(),
});

export async function POST(request: NextRequest) {
  try {
    // Rate limiting
    await limiter.check(10, 'CREATE_RESOURCE'); // 10 requests per minute
    
    // Authentication
    const user = await auth(request);
    if (!user) {
      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
    }
    
    // Validation
    const body = await request.json();
    const validatedData = createSchema.parse(body);
    
    // Database operation with transaction
    const resource = await db.$transaction(async (prisma) => {
      return prisma.resource.create({
        data: {
          ...validatedData,
          userId: user.id,
        },
        include: {
          user: {
            select: {
              name: true,
              avatar: true,
            },
          },
        },
      });
    });
    
    return NextResponse.json(resource, { status: 201 });
    
  } catch (error) {
    console.error('Resource creation error:', error);
    
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Validation failed', details: error.errors },
        { status: 400 }
      );
    }
    
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

# Functionality-First Prompt Pattern

"Build a [application type] with complete, production-ready functionality. 

CRITICAL: Every feature must be fully functional, not just visual:
- All forms must validate and save data to the database
- All buttons must perform real actions
- All API endpoints must handle errors properly
- All authentication must be secure and complete
- All user interactions must provide appropriate feedback

Do not create placeholder or demo functionality. Build real, working features that I can deploy and use with actual users."

# Security-First Requirements

"Implement comprehensive security measures:

MANDATORY SECURITY FEATURES:
1. Input validation and sanitization on all user inputs
2. SQL injection prevention using parameterized queries
3. XSS prevention by escaping all user content
4. CSRF protection on all forms
5. Rate limiting on authentication and API endpoints
6. Secure password hashing with bcrypt (min 12 rounds)
7. JWT token security with proper expiration and refresh
8. Role-based access control for all protected routes
9. Error handling that doesn't leak sensitive information
10. Secure headers (CSP, HSTS, X-Frame-Options)

Include security middleware and validation schemas for all endpoints."

# Error Handling Requirements

"Implement comprehensive error handling throughout the application:

CLIENT-SIDE ERROR HANDLING:
- React Error Boundaries for component crashes
- Global error boundary with user-friendly error messages
- Network error handling with retry logic
- Form validation errors with field-specific messages
- Loading states for all async operations
- Toast notifications for user feedback

SERVER-SIDE ERROR HANDLING:
- Global error handler middleware for unhandled errors
- Proper HTTP status codes for all error conditions
- Structured error logging without exposing sensitive data
- Database connection error recovery
- Rate limit error responses
- Validation error responses with helpful messages

EDGE CASE HANDLING:
- Empty states with helpful messages and actions
- Offline functionality where possible
- Graceful degradation for non-critical features
- Timeout handling for long-running operations

Include proper error types, logging, and user-friendly error messages throughout."

# Monitoring Setup

## Basic Health Monitoring
```typescript
// app/api/health/route.ts
import { NextResponse } from 'next/server';
import { db } from '@/lib/prisma';

export async function GET() {
  try {
    // Check database connectivity
    await db.$queryRaw`SELECT 1`;
    
    // Check external services
    const checks = {
      database: 'healthy',
      timestamp: new Date().toISOString(),
      uptime: process.uptime(),
      memory: process.memoryUsage(),
    };
    
    return NextResponse.json(checks);
  } catch (error) {
    console.error('Health check failed:', error);
    return NextResponse.json(
      { status: 'unhealthy', error: error.message },
      { status: 500 }
    );
  }
}
```

## Error Tracking
```typescript
// lib/monitoring.ts
export function logError(error: Error, context?: Record) {
  console.error('Application error:', {
    message: error.message,
    stack: error.stack,
    context,
    timestamp: new Date().toISOString(),
  });
  
  // In production, send to error tracking service
  if (process.env.NODE_ENV === 'production') {
    // Integrate with Sentry, LogRocket, etc.
  }
}

export function logEvent(event: string, data?: Record) {
  console.log('Application event:', {
    event,
    data,
    timestamp: new Date().toISOString(),
  });
  
  // In production, send to analytics service
  if (process.env.NODE_ENV === 'production') {
    // Integrate with PostHog, Mixpanel, etc.
  }
}
```

## Performance Monitoring
```typescript
// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  const start = Date.now();
  
  const response = NextResponse.next();
  
  response.headers.set('x-response-time', `${Date.now() - start}ms`);
  
  // Log slow requests
  const duration = Date.now() - start;
  if (duration > 1000) {
    console.warn(`Slow request: ${request.url} took ${duration}ms`);
  }
  
  return response;
}

export const config = {
  matcher: '/api/:path*',
};
```

# Maintenance Strategy

## Regular Update Schedule
- **Weekly**: Security updates for critical vulnerabilities
- **Monthly**: Minor dependency updates and bug fixes  
- **Quarterly**: Major feature updates and performance optimization
- **Annually**: Full security audit and architecture review

## Backup and Recovery
```bash
# Database backup script
#!/bin/bash
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
DB_NAME="your_db_name"
BACKUP_DIR="/backups"

# Create backup
pg_dump $DATABASE_URL > "$BACKUP_DIR/backup_$TIMESTAMP.sql"

# Compress backup
gzip "$BACKUP_DIR/backup_$TIMESTAMP.sql"

# Clean up old backups (keep last 30 days)
find $BACKUP_DIR -name "backup_*.sql.gz" -mtime +30 -delete

echo "Backup completed: backup_$TIMESTAMP.sql.gz"
```

## Performance Monitoring
- Monitor Core Web Vitals (LCP, FID, CLS)
- Track API response times and error rates
- Monitor database query performance
- Set up alerts for downtime or performance degradation

## Security Maintenance
- Regular dependency security scans
- Automated vulnerability testing
- Access log monitoring and analysis
- Regular backup and recovery testing