diff --git a/PROJECT_PAGE_ARCHITECTURE.md b/PROJECT_PAGE_ARCHITECTURE.md new file mode 100644 index 00000000..56eef8f0 --- /dev/null +++ b/PROJECT_PAGE_ARCHITECTURE.md @@ -0,0 +1,275 @@ +# 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/` 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`](./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/` 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. diff --git a/vibn-frontend b/vibn-frontend index e0844b5f..69c3a125 160000 --- a/vibn-frontend +++ b/vibn-frontend @@ -1 +1 @@ -Subproject commit e0844b5f2e9ae23f1d8a0b6b1c93187d5afcde2b +Subproject commit 69c3a1258c68633bfea8c48f6955ed63ea6ed1a4