# Rapid Full-Stack Prototyping
Build working full-stack web apps quickly (1-4 hours). Design first, code second, test third.
## When to Use
- User says "WEBAPP", "PROTOTYPE", "full-stack app", or "build a web application"
- Need both backend API + frontend UI
- Want speed + quality
## What You'll Build
- **Stack**: React + Vite + RESTful API (FastAPI/Express) + SQLite
- **Timeline**: 1-4 hours from idea to working app
- **Output**: Polished, functional prototype with keyboard shortcuts and clean UI
## The 3-Step Process
### Step 1: Design (5-10 min)
Create a text-based design showing:
```
UI LAYOUT:
[Header with Logo, Nav, Actions]
[Main Content - Left Sidebar | Center Panel | Right Info]
[Footer with Status]
USER INTERACTIONS:
1. Click "New" → Opens editor
2. Type text → Updates state
3. Press ⌘S → Saves via API
4. Click "History" → Opens panel
DATA MODELS:
- Item: {id, content, created_at}
- Revision: {id, item_id, content, timestamp}
API ENDPOINTS:
GET /api/items → List all
POST /api/items → Create new
GET /api/items/:id → Get one
PUT /api/items/:id → Update
GET /api/history/:id → Get revisions
```
### Step 2: Get Approval (30 sec)
Show the design → User says "looks good" → Start coding
### Step 3: Build (1-3 hours)
Use this stack (don't ask, just use):
- **Frontend**: React + Vite
- **Backend**: FastAPI (Python) or Express (Node)
- **Database**: SQLite
- **State**: useState + useEffect
Build in order:
1. Backend skeleton (30 min)
2. Core features (1-2 hours)
3. Polish + keyboard shortcuts (30 min)
4. Test with WEBTEST
---
## Rules for Claude
✅ **DO:**
- Design mock UI before any code
- Use React + RESTful API (default)
- Start coding immediately after approval
- Add keyboard shortcuts (⌘S, ⌘/, etc.)
❌ **DON'T:**
- Ask user to choose frameworks
- Skip the design phase
- Spend 30+ min researching simple features
- Build custom solutions for standard problems
## Core Principles
1. **Design Before Code** - Mock UI + interactions first, then build
2. **Use What You Know** - Familiar tools > "perfect" tools you don't know
3. **Single Source of Truth** - One state for each piece of data, sync explicitly
4. **Right Tool for Job** - Fighting a component's design? Wrong component
5. **Test Early** - Automated tests + real user feedback before launch
## Default Stack (Use This)
```
Frontend: React + Vite
Backend: FastAPI (Python) or Express (Node)
Database: SQLite
State: useState + useEffect
Styling: Vanilla CSS
```
**Why?** Fast setup, familiar patterns, good docs, zero config database.
**When to deviate:**
- User explicitly requests different stack → use their choice
- User needs SEO/SSR → use Next.js instead of Vite
- User says "no code" → suggest Bubble/Retool (explain trade-offs)
## Choosing Libraries
**When to add a library:**
- ✅ Would take > 1 hour to build from scratch
- ✅ Well-maintained (updated in last 6 months)
- ✅ You need > 30% of its features
**When to build it yourself:**
- ✅ Can be done in < 30 lines of code
- ✅ Only need 10% of library features
- ✅ Fighting the library's design
**Quick research (spend max 15 min):**
```bash
# 1. Search
WebSearch: "best [feature] library react 2025"
# 2. Check npm
npm info [package-name]
# Look at: downloads/week, last publish, dependencies count
# 3. Test
# Try basic example - works in 15 min? Keep it. Doesn't? Try next option.
```
**Examples:**
```javascript
// ❌ Don't need library for:
fetch() // axios is overkill
// don't force WYSIWYG when plain text works
Intl.DateTimeFormat // moment.js is heavy
// ✅ Use library for:
// complex parsing + preview
// diff algorithm is non-trivial
// syntax highlighting + LSP
```
## Project Structure
```
project/
├── backend/
│ ├── server.py # FastAPI app
│ └── requirements.txt # Python deps
├── frontend/
│ ├── src/
│ │ ├── App.jsx # Main component
│ │ ├── App.css # Styles
│ │ └── main.jsx # Entry point
│ ├── package.json
│ └── vite.config.js # Vite config with proxy
├── launcher-script # CLI to start both servers
├── install.sh # Setup script
└── README.md # Documentation
```
## Build Workflow
### Phase 0: Design (15-30 min)
See "The 3-Step Process" above - create text-based design with UI layout, interactions, data models, and API endpoints. Show to user → get approval → start coding.
### Phase 1: Backend + Frontend Skeleton (30 min)
**Backend:**
```python
# Define models → Create CRUD endpoints → Test with curl
# FastAPI example:
@app.get("/api/items")
async def list_items(): ...
@app.post("/api/items")
async def create_item(item: Item): ...
```
**Frontend:**
```bash
npm create vite@latest my-app -- --template react
cd my-app && npm install
# Configure vite.config.js proxy to backend
# Test connection with /api/health endpoint
```
### Phase 2: Core Features (1-2 hours)
- Build one feature at a time
- useState for local state, useEffect for side effects
- Single source of truth (one canonical state, sync others from it)
- Test each feature before moving to next
### Phase 3: Polish (30 min)
```javascript
// Add keyboard shortcuts
useEffect(() => {
const handleKeyDown = (e) => {
if (e.metaKey) {
if (e.key === 's') { e.preventDefault(); save(); }
if (e.key === '/') { e.preventDefault(); showHelp(); }
}
};
window.addEventListener('keydown', handleKeyDown);
return () => window.removeEventListener('keydown', handleKeyDown);
}, []);
```
- Add help modal (⌘/)
- Add button active states
- Add status feedback ("✓ Saved")
- Add tooltips with keyboard shortcuts
### Phase 4: Test (Use WEBTEST)
```bash
# Run automated tests
WEBTEST # Triggers testing-webapps skill
# Manual checks:
# - All buttons work
# - Data persists after save
# - No console errors
# - Keyboard shortcuts work
```
## Common Mistakes
### 1. Multiple Sources of Truth
```javascript
// ❌ Bad: Three states for same data
const [editorContent, setEditorContent] = useState('');
const [diffContent, setDiffContent] = useState('');
const [previewContent, setPreviewContent] = useState('');
// ✅ Good: One source, sync to views
const [content, setContent] = useState('');
useEffect(() => {
editorRef.current?.setContent(content);
}, [viewMode, content]);
```
### 2. Fighting Component Design
```javascript
// ❌ Bad: Complex CSS to hide UI elements
.editor .toolbar { display: none !important; }
.editor .tabs { visibility: hidden !important; }
// ✅ Good: Use simpler component