mawkone
1c3e3c96b3
- Bumps vibn-frontend submodule to the new tabbed project shell - Adds PROJECT_PAGE_ARCHITECTURE.md documenting the section charters, boundary rules, and phased delivery plan Phase 1 ships only the tab shell + Product tab live data (Gitea file tree per codebase). Infra/Hosting tabs are stubbed and the old 15 sidebar routes are intentionally untouched during migration. Made-with: Cursor
276 lines
10 KiB
Markdown
276 lines
10 KiB
Markdown
# 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`](./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.
|