vibn-agent-runner/PROJECT_PAGE_ARCHITECTURE.md

Project Page Architecture — Product / Infrastructure / Hosting

The plan to collapse the 16-page sidebar mess at /[workspace]/project/[projectId]/* into 3 founder-friendly sections, and to make /project/<id> actually reflect what the AI is doing in the dev container instead of stale Gitea/prod-Coolify data.

Companion to: AI_PATH_B_EXECUTION_PLAN.md (Path B is the engine; this doc is the dashboard for it).

Status: week 1 doc + home-page redesign in flight (2026-04-28).

---

1. Why this exists

Today the project page (/[workspace]/project/[projectId]) shows two tiles — Code + Infrastructure — and links to a sidebar with 16 sub-routes (build, run, infrastructure, deployment, overview, insights, analytics, prd, tasks, settings, assist, design, growth, grow, mvp-setup, code — the last of which doesn't exist as a route, so the home tile is a dead link).

Two structural problems:

1. The sidebar grew without an anchor concept. Founders have no mental model of what the 16 pages map to; they just see a list and click around hoping for the right one. Half the pages are placeholders ("Coming soon"); the rest overlap.
2. None of the data sources have been updated for Path B. The Code tile reads the Gitea repo (production master branch), but the AI now writes to the dev container's /workspace, often without pushing for hours. The Infrastructure tile reads production Coolify apps; new dev_server.start previews don't show up anywhere. So when AI does great work in chat, the project page doesn't update — the user has to tab back to chat to see anything.

---

2. The framing

Three sections, founder-friendly names, every project on Vibn maps cleanly into all three:

Section	What it is	Founder asks…
Product	Custom code, design, content built for THIS vision	"What did I build?"
Infrastructure	Reusable, swappable third-party services (auth, db, email, payments…)	"What do I depend on?"
Hosting	Where the product runs and how people reach it (Coolify, domain, observability, cost)	"Where does it live?"

The boundary rule

Custom code = Product. Third-party service = Infrastructure. Runtime + reachability = Hosting.

Concrete edge cases:

• A custom /api/upload endpoint that calls S3 → endpoint is Product, S3 bucket + credentials are Infrastructure.
• Custom job that sends a welcome email → job is Product, the job runner (Sidekiq/BullMQ) and email service (Resend) are Infrastructure.
• Webhook handler that processes Stripe events → handler is Product, Stripe is Infrastructure.
• Coolify scheduled task that runs your code → your code is Product, Coolify itself is Hosting.

---

3. Charters

Product

Everything custom-built for this specific vision. The unique IP that wouldn't exist without this product.

Includes:

• Frontend web app
• Marketing site
• Custom backend code & APIs
• Custom business logic
• Custom jobs / runners (the code, not the runner)
• Brand, copy, design system
• The repository itself
• Customer base — the actual users you've earned

Rule: if you wrote it for this product, it's Product. If it's node_modules or a third-party SDK, it's not.

Infrastructure

The reusable, swappable services your product depends on. The annoying multi-vendor world where you have to pick a provider.

Includes:

• Auth provider (Clerk, Pocketbase, Authentik, Google OAuth, …)
• Database (Postgres, MySQL, MongoDB, Redis, …)
• File storage (S3, R2, MinIO)
• Email (Resend, SendGrid, SES)
• Payments (Stripe, Paddle, Lemon Squeezy)
• Analytics (Plausible, PostHog, GA)
• Search (Algolia, Meili, Typesense)
• LLM provider (OpenAI, Anthropic, Gemini, Vertex)
• Queues, maps, SMS, push notifications, …
• Secrets and API keys that wire all of the above

Rule: if you could swap the vendor without changing your product code, it's Infrastructure.

Hosting

Where the product physically runs and how people reach it.

Includes:

• Container runtime (Coolify in our case)
• Domain + DNS + SSL
• CDN / edge
• Observability (logs, errors, uptime)
• Backups
• Monthly cost

Rule: it's about runtime and reachability, not about what the software does.

---

4. Future sections (deferred)

Add as separate top-level cards once they become real concerns:

• Models — for AI-heavy products: which LLMs, which embedding model, prompt versions, eval scores, cost-per-call.
• Analytics — when there are real users worth measuring.
• Marketing — campaigns, blog, SEO, social, when there's a growth motion.
• Compliance — Terms, Privacy, GDPR, SOC2, when shipping to paying customers.
• Support — helpdesk, chat, status page, when there are customers complaining.
• Team — when the project has more than one collaborator.

Same charter template each time. Same rule: code = Product, swappable = Infrastructure, runs/reachable = Hosting, otherwise it needs its own section.

---

5. Mapping today → tomorrow

Today's page	Where it goes	Notes
(home)/page.tsx	New (home)/page.tsx (3-card grid)	Full redesign
code (404)	product/ (new)	Stub the route, point home tile at it
build	Subroute under product/files (later)	Heavy 1626 lines; preserve the file tree component
run	hosting/	Production runtime
infrastructure	hosting/	Same data, different name
deployment	hosting/deploys (later)	Deploy history is Hosting
overview	Subroute under product/ or merged into home	Decide once we see how home feels
prd	Subroute under product/ (vision)	Or its own "Define" section if we add one
tasks	Subroute under product/ (roadmap)	Or its own section later
assist	product/ (it's emails/chat your product sends)	These ARE product features
design	product/design	Custom for this vision
growth, grow, analytics, insights, mvp-setup	Defer, probably absorbed into a future "Analytics" or "Marketing" section	Many are placeholders today
settings	Top-right gear (lives outside the 3 sections)	Project-level meta

Net: 16 routes → 3 sections (+ settings). 8+ pages get rationalized into nothing because they were duplicating their neighbors.

---

6. Phased delivery

Phase 1 — Tab navigation + section stubs (this session)

The three sections are TABS at the project level, not a card-grid landing page. A founder lands on the project URL and is immediately inside Product (the default tab); flipping to Infrastructure or Hosting is one click and stays in the same view. No intermediate "click a tile to drill in" step.

URL shape:

/[workspace]/project/[id]                 → 308 redirect to /product
/[workspace]/project/[id]/product         → Product tab
/[workspace]/project/[id]/infrastructure  → Infrastructure tab
/[workspace]/project/[id]/hosting         → Hosting tab

A shared layout at the project root renders:

• Project header (name, vision, stage pill, settings gear)
• Tab bar (Product · Infrastructure · Hosting) — active tab highlighted; each tab carries a tiny status dot (green/amber/grey)
• Slot for the active tab's page

The current (home)/page.tsx (the two-tile landing) is replaced by the redirect.

Don't kill anything in (workspace)/. Existing 16 routes stay alive while we migrate. Sidebar still works for them.

Phase 2 — Wire data sources

• Product card reads from the dev container's /workspace:
  • File count + recent edits via fs.list against the project's dev container
  • User count from the project's auth provider (Pocketbase / Clerk / etc.)
  • Frontend URL from dev_server.list or production apps_list
• Infrastructure card reads from Coolify databases, env vars, and known integrations:
  • Database type + size
  • Auth provider name
  • Wired services (any env var matching STRIPE_*, RESEND_*, etc.)
• Hosting card reads from Coolify apps + domains + container metrics:
  • Production URL, SSL status, last deploy
  • Monthly cost (Coolify resource usage × pricing)
  • Recent error count (from logs)

Phase 3 — Section detail pages

Build each of /product, /infrastructure, /hosting as a real, useful surface. Each page can have internal subnav for the bits listed in its charter (e.g., Product has Frontend, Backend, Jobs, Brand, Customers; Infrastructure has Auth, DB, Storage, Email, Payments, …).

Phase 4 — Migration / deletion

Once the new structure is proven, redirect the legacy routes:

• code → product
• build → product/files
• run → hosting
• infrastructure → hosting
• deployment → hosting/deploys
• prd, tasks, assist → product/...
• growth, grow, analytics, insights, mvp-setup → soft-delete with a tombstone redirect to product or to a future section page.

---

7. Open questions

• Where do the chat threads live? They're a per-project conversation surface today (right rail in the chat panel). I'd argue they're not a section — they're across sections, like the AI is. Keep as the persistent right rail.
• Settings is technically project-level meta, not one of the three sections. Where does it surface? Gear icon in the page header, opens settings as a side sheet or as a separate route. Decide when we get there.
• Mobile layout — three cards stack vertically; no special layout needed. The section detail pages need a layout pass when we get to phase 3.

---

8. Success criteria

You should be able to look at /project/<id> after AI activity in chat and immediately see:

1. "What did the AI just build?" → Product card updated count of files + recent diffs.
2. "What's it depending on?" → Infrastructure card shows the new Postgres, the new Stripe key, etc.
3. "Is it live?" → Hosting card shows the dev preview URL or the production URL with status.

If any of those three answers requires going back to the chat or checking another page, the redesign hasn't worked.