clawd/skills/app-builder/SKILL.md

name, description

name

description

app-builder

Build and deploy web applications following a standardized process. Use when asked to create a new app, prototype, SaaS tool, or web project. Covers the full lifecycle from ideation through production deployment with a repeatable stack (React + Vite + Tailwind, Elysia + Bun, PostgreSQL + Drizzle, BetterAuth, Dokploy). Use for any request like "build me an app", "create a tool", "make a dashboard", or "prototype this idea".

App Builder

Standardized process for building and deploying web applications. Every app follows the same stack, structure, and lifecycle.

Stack

Layer	Tech	Why
Frontend	React + Vite + TypeScript + Tailwind	Fast, typed, utility CSS
Backend	Elysia + Bun + TypeScript	Fast, type-safe, great DX
Database	PostgreSQL + Drizzle ORM	Industry standard + lightweight ORM
Auth	BetterAuth (invite-only signup)	TypeScript-native, modern
AI (if needed)	LangChain.js	Model-agnostic, swap providers
Email (if needed)	Resend	Simple API, 3k free/month
Jobs (if needed)	pg-boss	Postgres-backed job queue
Deploy	Dokploy (self-hosted)	Full control, predictable costs
Git	Gitea (git.infra.nkode.tech)	Self-hosted, private

Lifecycle Phases

Phase 1: Ideation

1. Gather requirements from the user (what, who, why)
2. Write a requirements doc at notes/projects/<app-name>/requirements.md
3. Research competitors if relevant
4. Get user approval on scope before proceeding

Phase 2: Scaffold

1. Create project directory at /home/clawdbot/clawd/<app-name>
2. Use the template structure from assets/template/ as a starting point
3. Create Gitea repos (one for monorepo, or separate frontend/backend)
4. Customize schema for the specific app
5. Ensure Hammer service account routes are included

Phase 3: Development

1. Build features incrementally
2. Write tests from day one
3. Use local docker-compose for development
4. Commit and push frequently
5. Update the task queue dashboard with progress

Phase 4: Test Deployment

1. Create Dokploy compose deployment
2. Deploy to test subdomain: test-<app>.donovankelly.xyz
3. Set environment variables in Dokploy
4. Store all credentials in Bitwarden shared vault
5. Verify basic functionality

Phase 5: User Review

1. Notify user that test deployment is ready
2. User tests and provides feedback
3. Iterate on feedback (return to Phase 3 as needed)
4. Get explicit approval before going to production

Phase 6: Production Deployment

1. Create production Dokploy compose
2. Deploy to production subdomain: <app>.donovankelly.xyz
3. Configure production environment variables
4. Verify all features work
5. Set up monitoring/health checks

Phase 7: Maintenance

• Feature requests go through test env first
• DB migrations via Drizzle (bun run db:push for dev, bun run db:migrate for prod)
• Keep staging synced with prod schema
• Rollback: Dokploy supports redeploying previous builds

Every App Must Have

• BetterAuth with disableSignUp: true (invite-only) — NO EXCEPTIONS. Every app requires authentication. No public-facing pages without login.
• Hammer service account + /api/hammer/* routes (bearer token auth)
• All API routes behind auth (session or bearer token)
• Structured logging (console.log with JSON in prod)
• Unit tests (Vitest for frontend, bun:test for backend)
• Health check endpoint (GET /api/health) — only unauthenticated route allowed
• docker-compose.yml (local dev)
• docker-compose.dokploy.yml (production)
• .env.example with all required vars documented
• All secrets in Bitwarden shared vault

Auth is not optional. Even internal tools, dashboards, and single-user apps must have login. If Donovan is the only user, he still logs in. No public read access to any data.

Environment Variable Naming

Standard env vars across all apps:

DATABASE_URL=postgresql://...
PORT=3001
NODE_ENV=production
APP_URL=https://app.<domain>
ALLOWED_ORIGINS=https://app.<domain>
BETTER_AUTH_SECRET=<random>
HAMMER_API_KEY=<random>
RESEND_API_KEY=<if needed>
FROM_EMAIL=<if needed>

Credential Management

• All credentials go in Bitwarden shared vault (org: Hammer's Credentials)
• Create a Bitwarden entry per app: <App Name> (<domain>)
• Store HAMMER_API_KEY as a field on the app's BW entry
• Add HAMMER_API_KEY to ~/.clawdbot/.env as HAMMER_<APP>_API_KEY
• Never hardcode secrets, never echo them in chat

Dokploy Deployment

See references/deploy.md for detailed Dokploy deployment steps.

Rollback Protocol

See references/rollback.md for rollback and recovery procedures.

DB Migration Strategy

See references/migrations.md for database migration best practices.

Legal & Payments

See references/legal-payments.md for legal protection and payment processing options.

Project Documentation

For every app, create in notes/projects/<app-name>/:

• README.md — overview, stack, status
• requirements.md — feature spec
• architecture.md — technical design (if complex)
• feasibility.md — assessment (if needed)