133 lines
5.1 KiB
Markdown
133 lines
5.1 KiB
Markdown
---
|
|
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)
|