docs: heavily compress and simplify remaining reference files to represent current state
This commit is contained in:
@@ -1,275 +1,11 @@
|
||||
# Project Page Architecture — Product / Infrastructure / Hosting
|
||||
# Project Page Architecture
|
||||
|
||||
> 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).
|
||||
> **Note:** The UI was heavily refactored. The primary surfaces for a project are now:
|
||||
|
||||
---
|
||||
1. **The Plan Tab (`/plan`):** Contains the project's vision/objective document, tasks, decisions, and raw ideas. The AI acts as a scribe here.
|
||||
2. **The Product Tab (`/product`):** Lists the live codebases (Gitea) and running images (Docker containers).
|
||||
3. **The Infrastructure Tab (`/infrastructure`):** Lists the underlying resources (PostgreSQL databases, Redis, etc.) managed by Coolify.
|
||||
4. **The Hosting Tab (`/hosting`):** Lists live runtime environments, logs, and preview URLs.
|
||||
5. **The Chat Panel:** Available on all project surfaces as a slide-out, used to orchestrate work.
|
||||
|
||||
## 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.
|
||||
*(Refer to `vibn-frontend/app/[workspace]/project/[projectId]` for the UI implementation).*
|
||||
|
||||
Reference in New Issue
Block a user