# Full-Stack App Cookbook > Deploy a full-stack application (Next.js + Go backend) built entirely by Claude through the threesix.ai infrastructure. ## Overview This cookbook creates and deploys a complete full-stack application using **agent-driven development**: ``` POST /project/create-and-build ↓ Creates: Gitea repo + DNS + Woodpecker CI + K8s deployment ↓ Enqueues build task with comprehensive prompt ↓ Worker picks up task → Claude builds the entire stack ↓ Agent commits + pushes ↓ CI builds and deploys ↓ Live full-stack app ``` **Claude builds everything from scratch: Next.js frontend with shadcn/ui, Go backend API, Docker configs, and CI pipeline.** --- ## Prerequisites ### API Access ```bash export RDEV_API_URL="https://rdev.masq-ops.orchard9.ai" export RDEV_API_KEY="" ``` ### Infrastructure Required - rdev-api running with embedded worker - Gitea at https://git.threesix.ai - Woodpecker CI at https://ci.threesix.ai - claudebox-0 pod running in rdev namespace --- ## Step 1: Create Project and Build Full-Stack App Single API call that creates infrastructure AND enqueues the full-stack build: ```bash curl -X POST "$RDEV_API_URL/project/create-and-build" \ -H "X-API-Key: $RDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "my-fullstack-app", "description": "Full-stack app with Next.js frontend and Go backend", "build": { "prompt": "Build a full-stack task management application with the following structure:\n\nFRONTEND (Next.js 14 + shadcn/ui):\n- Create a Next.js 14 app with App Router in /frontend\n- Use shadcn/ui for all components (install with npx shadcn-ui@latest init)\n- Dark theme with modern aesthetic\n- Pages: Dashboard showing tasks, Add Task form, Task detail view\n- Use Tailwind CSS for styling\n- Connect to backend API at /api proxy\n\nBACKEND (Go):\n- Create a Go HTTP server in /backend using chi router\n- Endpoints: GET /api/tasks, POST /api/tasks, GET /api/tasks/{id}, DELETE /api/tasks/{id}\n- In-memory task storage (no database needed)\n- Structured JSON responses\n- CORS middleware for frontend\n\nDOCKER:\n- /frontend/Dockerfile: Multi-stage build for Next.js (node:20-alpine)\n- /backend/Dockerfile: Multi-stage build for Go (golang:1.22-alpine)\n- /docker-compose.yml: Run both services, frontend proxies to backend\n\nCI/CD:\n- /.woodpecker.yml: Build both images, push to registry, deploy to k8s\n\nCreate all necessary files including package.json, go.mod, and configuration files.", "auto_commit": true, "auto_push": true } }' ``` **Response:** ```json { "project": { "project_id": "my-fullstack-app", "domain": "xyz789ab.threesix.ai", "git": { "html_url": "https://git.threesix.ai/jordan/my-fullstack-app" } }, "build": { "task_id": "task-uuid", "status": "pending", "status_url": "/builds/task-uuid" } } ``` --- ## Step 2: Monitor Build Progress Poll the build status: ```bash curl -s "$RDEV_API_URL/builds/{task_id}" \ -H "X-API-Key: $RDEV_API_KEY" | jq . ``` **Status progression:** `pending` → `running` → `completed` (or `failed`) Full-stack builds take longer than simple landing pages. Expect 2-5 minutes. When completed: ```json { "task_id": "task-uuid", "status": "completed", "result": { "success": true, "commit_sha": "def456", "files_changed": [ "frontend/package.json", "frontend/app/page.tsx", "frontend/app/layout.tsx", "frontend/components/task-list.tsx", "frontend/components/add-task-form.tsx", "frontend/Dockerfile", "backend/main.go", "backend/go.mod", "backend/Dockerfile", "docker-compose.yml", ".woodpecker.yml" ], "duration_ms": 180000 } } ``` --- ## Step 3: Monitor CI Pipeline The agent's push triggers Woodpecker CI to build both services: ```bash curl -s "$RDEV_API_URL/projects/my-fullstack-app/pipelines" \ -H "X-API-Key: $RDEV_API_KEY" | jq '.data[0]' ``` Pipeline stages: 1. Build frontend Docker image 2. Build backend Docker image 3. Push both to registry 4. Deploy to Kubernetes Wait for `status: "success"`. --- ## Step 4: Verify Deployment ```bash # Check site is live curl -I https://xyz789ab.threesix.ai # Test frontend loads curl -s https://xyz789ab.threesix.ai | head -20 # Test backend API curl -s https://xyz789ab.threesix.ai/api/tasks | jq . # Open in browser open https://xyz789ab.threesix.ai ``` --- ## Iterating on the App ### Add a Feature ```bash curl -X POST "$RDEV_API_URL/projects/my-fullstack-app/builds" \ -H "X-API-Key: $RDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Add task priority levels (low, medium, high) with color-coded badges in the UI. Update the backend Task struct and frontend components to support priorities. Add a priority filter dropdown on the dashboard.", "auto_commit": true, "auto_push": true }' ``` ### Fix a Bug ```bash curl -X POST "$RDEV_API_URL/projects/my-fullstack-app/builds" \ -H "X-API-Key: $RDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Fix the task deletion - ensure the DELETE endpoint returns 204 No Content and the frontend removes the task from the list immediately without requiring a page refresh.", "auto_commit": true, "auto_push": true }' ``` ### Add Authentication ```bash curl -X POST "$RDEV_API_URL/projects/my-fullstack-app/builds" \ -H "X-API-Key: $RDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Add simple JWT authentication:\n- Backend: Add /api/auth/login endpoint that accepts username/password and returns JWT\n- Backend: Add auth middleware to protect /api/tasks endpoints\n- Frontend: Add login page with shadcn form components\n- Frontend: Store JWT in localStorage, include in API requests\n- Create a demo user (admin/admin123) for testing", "auto_commit": true, "auto_push": true }' ``` Each build: 1. Claude clones the existing repo 2. Makes the requested changes 3. Commits and pushes 4. CI deploys automatically --- ## Alternative Prompts ### E-commerce Storefront ```bash curl -X POST "$RDEV_API_URL/project/create-and-build" \ -H "X-API-Key: $RDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "my-store", "description": "E-commerce storefront", "build": { "prompt": "Build an e-commerce storefront:\n\nFRONTEND: Next.js 14 with shadcn/ui, dark theme\n- Product grid with images, prices, descriptions\n- Product detail page\n- Shopping cart (localStorage)\n- Checkout form (no payment processing)\n\nBACKEND: Go with chi router\n- GET /api/products - list products\n- GET /api/products/{id} - product detail\n- POST /api/orders - create order (log to console)\n- Seed with 6 sample products\n\nInclude Dockerfiles and .woodpecker.yml for CI/CD.", "auto_commit": true, "auto_push": true } }' ``` ### Dashboard App ```bash curl -X POST "$RDEV_API_URL/project/create-and-build" \ -H "X-API-Key: $RDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "my-dashboard", "description": "Analytics dashboard", "build": { "prompt": "Build an analytics dashboard:\n\nFRONTEND: Next.js 14 with shadcn/ui + recharts\n- Dashboard with 4 stat cards (users, revenue, orders, growth)\n- Line chart showing weekly trends\n- Bar chart showing top products\n- Recent activity table\n- Dark theme, responsive grid layout\n\nBACKEND: Go with chi router\n- GET /api/stats - return dashboard statistics\n- GET /api/trends - return weekly trend data\n- GET /api/activity - return recent activity\n- Generate realistic sample data\n\nInclude Dockerfiles and .woodpecker.yml for CI/CD.", "auto_commit": true, "auto_push": true } }' ``` --- ## Adding Custom Domains ```bash # Add custom domain curl -X POST "$RDEV_API_URL/projects/my-fullstack-app/domains" \ -H "X-API-Key: $RDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{"domain": "app.mycompany.com"}' # List all domains curl -s "$RDEV_API_URL/projects/my-fullstack-app/domains" \ -H "X-API-Key: $RDEV_API_KEY" | jq '.data.domains' ``` --- ## Teardown ```bash curl -X DELETE "$RDEV_API_URL/project/my-fullstack-app" \ -H "X-API-Key: $RDEV_API_KEY" ``` Removes: DNS records, K8s deployment, project metadata. Gitea repo preserved for safety. --- ## E2E Test Script Run the full flow: ```bash ./cookbooks/scripts/fullstack-test.sh run my-test-fullstack ``` Check status: ```bash ./cookbooks/scripts/fullstack-test.sh status my-test-fullstack ``` Cleanup: ```bash ./cookbooks/scripts/fullstack-test.sh teardown my-test-fullstack ``` --- ## Architecture ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Agent-Driven Full-Stack App │ │ │ │ POST /project/create-and-build │ │ │ │ │ ├──► Gitea: creates repo │ │ ├──► Cloudflare: creates DNS │ │ ├──► Woodpecker: activates CI │ │ ├──► K8s: creates Deployment/Service/Ingress │ │ └──► Work Queue: enqueues build task │ │ │ │ │ ▼ │ │ Worker polls queue, claims task │ │ │ │ │ ▼ │ │ Claude Code executes in claudebox-0: │ │ - Clones repo │ │ - Creates Next.js frontend with shadcn/ui │ │ - Creates Go backend with chi router │ │ - Writes Dockerfiles and CI config │ │ - Commits and pushes │ │ │ │ │ ▼ │ │ Woodpecker CI triggered by push: │ │ - Builds frontend Docker image │ │ - Builds backend Docker image │ │ - Pushes to registry │ │ - Deploys to K8s │ │ │ │ │ ▼ │ │ Full-stack app live at https://{slug}.threesix.ai │ │ - Frontend: Next.js + shadcn/ui │ │ - Backend: Go API │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## Troubleshooting ### Build stuck in pending ```bash # Check worker status curl -s "$RDEV_API_URL/workers" -H "X-API-Key: $RDEV_API_KEY" | jq '.data.summary' # Should show at least 1 idle worker ``` ### Build failed ```bash # Get build details with full output curl -s "$RDEV_API_URL/builds/{task_id}" -H "X-API-Key: $RDEV_API_KEY" | jq '.result' # Check rdev-api logs for worker errors ./scripts/logs.sh -e ``` ### Pipeline not triggering ```bash # Check if commit was pushed curl -s "https://git.threesix.ai/api/v1/repos/jordan/my-fullstack-app/commits" | jq '.[0]' # Check Woodpecker open https://ci.threesix.ai/jordan/my-fullstack-app ``` ### Frontend/Backend connection issues ```bash # Check both containers are running kubectl get pods -n projects -l app=my-fullstack-app # Check frontend logs kubectl logs -n projects -l app=my-fullstack-app -c frontend # Check backend logs kubectl logs -n projects -l app=my-fullstack-app -c backend ``` --- ## Related - [Landing Page Cookbook](./landing-page.md) - Simpler single-page deployment - [Worker Pool Guide](../.claude/guides/services/worker-pool.md) - [Build Orchestration](../.claude/guides/services/build-orchestration.md)