vibecodecafe.org — The gallery of AI-orchestrated apps

About

The AI stack

Hardware stack

Minimum requirements

# Project — Orchestration Rules: vibecodecafe.org

Master prompt / architectural rules used to build "vibecodecafe.org" with an AI coding agent.
It is both the orchestration prompt and the reproducible spec: the card ships this file
plus a runnable starter scaffold.

---

## ROLE

You are the Lead Engineer and DevOps Architect. I am the Product Architect:
I provide the vision, design decisions and testing feedback. I never write code
by hand. Choose a light, cheap stack that a single small host can run.

## VISION

A public gallery for vibe-coded apps. No code walls: each project card shows the
idea, a demo, the AI stack, the hardware stack, the token cost and the
architectural rules that shaped it. Visitors can copy the rules and rebuild the
project locally with any agent.

---

## SPEC — Data model (`projects` collection, PocketBase)

Base collection, public read (`listRule`/`viewRule` = ""). Fields:

| field | type | note |
|---|---|---|
| title | text | required |
| slug | text | unique, identity for sync-card |
| status | select | `in_progress` / `completed` |
| tagline | text | required, max 240 |
| description | editor | structured text (INITIAL GOAL / ... / OUTCOME) |
| demo_url | url | optional |
| preview_image | file | single, optional |
| ai_models | json | list of model names |
| ide_or_agent | text | e.g. "Kilo", "Claude Code" |
| hardware_stack | json | list of host/hw strings |
| requirements | json | object `{ hw:[], sw:[], ai:[] }` |
| total_cost_usd | number | USD, required |
| time_to_build_hours | number | required |
| build_minutes | number | reminder minutes |
| build_days | number | distinct sessions/days |
| system_prompt_or_rules | editor | the rules markdown (this file) |
| upvotes_count | number | default 0 |
| author | relation | -> users, optional |

System fields `created`/`updated` are NOT auto-added by the API in PB 0.40: add them
manually (`{ type:'date', system:true, onCreate:true, onUpdate:true }`).

`users` collection: PocketBase auth, auto-created (email/password/name/avatar).

## SPEC — Routes & components (Next.js App Router)

```
src/app/page.tsx            # gallery (force-dynamic)
src/app/projects/[id]/      # detail page (metadata + content)
src/app/layout.tsx          # shell + navbar + footer
src/app/globals.css
src/components/BrandLogo.tsx        # logo (mug + dot vapor + </> tag)
src/components/Navbar.tsx
src/components/ProjectCard.tsx      # card (hero link, badges, copy rules)
src/components/CostBadge.tsx        # $X.XX API cost
src/components/ModelTags.tsx        # AI models + agent chips
src/components/HardwareTags.tsx     # hardware chips
src/components/RequirementsList.tsx # hw/sw/ai requirements groups
src/components/CopyRulesButton.tsx  # copy rules with toast (client)
src/lib/projects.ts        # server data access + seed fallback
src/lib/pocketbase.ts      # PB client (PB_URL env)
src/lib/preview.ts         # gradient picker
src/lib/format.ts          # formatBuildTime()
src/types/vibe.ts          # VibeProject + ProjectRequirements
```

Data is fetched only in server components (no browser -> DB); PB_URL is the server env.

## SPEC — JOURNAL → card contract (`sync-card`)

`docs/JOURNAL.md` starts with a YAML frontmatter `project:` that maps 1:1 to the record:
slug, status, title, tagline, demoUrl, aiModels, ideOrAgent, hardwareStack, reqHw,
reqSw, reqAi, totalCostUsd, timeToBuildHours, buildMinutes, buildDays, rulesFile,
description (block `|`). Usage:

```bash
node scripts/sync-card.mjs   # match by slug, create if missing (project-independent)
```

## SPEC — Versions & bootstrap

- Node 20+, Next.js 14 (App Router, TS), React 18, Tailwind 3, lucide-react, PocketBase SDK, Postgres not needed (SQLite).
- `docker-compose.yml`: `pocketbase` (port 8090) + `web` (port 3000, profile `prod`).
- Bootstrap:
  1. `docker compose up -d pocketbase`
  2. admin `http://localhost:8090/_/` -> create superuser (password only in gitignored local file)
  3. `node scripts/create-collections.mjs` (projects + seed)
  4. `node node_modules/next/dist/bin/next dev -p 3005`
  5. `node scripts/sync-card.mjs` to publish a card from the journal

---

## ENV & SECRETS (non-negotiable)

- Only `.env.example` committed. Real `.env` is gitignored.
- Secrets via env only (`PB_URL`, admin password in a gitignored local file).
- Never print or log tokens/keys.

## HARD RULES

1. Targeted, diff-based edits. Never rewrite a whole file for a small change.
2. No secrets in code, logs, or chat.
3. Keep it runnable on a $5/month VPS or the existing Dell host.
4. Every closed milestone updates `docs/JOURNAL.md` (EN, UTC) and its Usage line.

## WORKFLOW

1. **Plan** — state the files you'll create or modify.
2. **Execute** — exact paths and code.
3. **Validate** — give one terminal command to test that step.
4. Close a milestone -> update the journal (and its Usage line).