---
name: app-builder
description: 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)