From 904e7bfbcaaa462e121b83b18c4a92d41bc3265f Mon Sep 17 00:00:00 2001
From: mawkone <mark@getacquired.com>
Date: Sun, 1 Mar 2026 21:09:10 -0800
Subject: [PATCH] docs: capture product lifecycle design and surfaces/libraries
 mapping

Made-with: Cursor
---
 architecture.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/architecture.md b/architecture.md
index 2792daeb..36c177c3 100644
--- a/architecture.md
+++ b/architecture.md
@@ -273,6 +273,55 @@ Atlas has access to real-time web search via [Jina AI's search endpoint](https:/
 
 ---
 
+## Product Lifecycle (Current Design)
+
+### Correct sequence — not yet fully implemented
+
+```
+1. Create project (name only — no scaffold yet)
+        ↓
+2. Atlas discovery conversation
+   - Understands the product concept
+   - Determines product type (SaaS / Marketplace / E-commerce / AI / Website / Mobile)
+   - Determines required surfaces (Web App, Marketing Site, Admin, Mobile, Email, Docs)
+   - Determines design package per surface
+   - Generates PRD with all of the above as structured data
+        ↓
+3. Architect agent
+   - Reads PRD (product type, surfaces, design choices)
+   - Designs technical solution and data model
+   - Generates Gitea repo scaffold tailored to the specific surfaces needed
+   - NOT a generic Turborepo template — apps/ reflects exactly what was decided
+        ↓
+4. Builder / Orchestrator
+   - Reads PRD + architecture
+   - Builds the product surface by surface
+        ↓
+5. Active (Theia IDE + Orchestrator for ongoing work)
+```
+
+### What is built today (and needs to change)
+
+| Step | Current behaviour | Correct behaviour |
+|------|------------------|-------------------|
+| Project creation | Creates Gitea repo + generic Turborepo scaffold immediately | Create project record only — no repo yet |
+| Atlas | Saves PRD markdown + sets stage to `architecture` | Also saves `productType` and `surfaces[]` as structured fields |
+| Design page | Shows Turborepo `apps/` from Gitea | Reads `surfaces[]` from PRD, shows theme picker per surface |
+| Architect | Not built yet | Reads PRD + surfaces, generates tailored Gitea scaffold |
+
+### Design surfaces and recommended libraries
+
+| Surface | When needed | Library options |
+|---------|-------------|----------------|
+| **Web App** | SaaS, Marketplace, AI Product | shadcn/ui, Mantine, HeroUI, Tremor |
+| **Marketing Site** | Almost every product | DaisyUI, HeroUI, Aceternity UI, Tailwind only |
+| **Admin / Internal** | SaaS, Marketplace, E-commerce | Mantine, shadcn/ui, Tremor |
+| **Mobile App** | Mobile-first products | NativeWind, Gluestack, RN Paper |
+| **Email** | SaaS, E-commerce, Marketplace | React Email + Resend |
+| **Docs / Content** | Developer tools, complex products | Nextra, Starlight, Docusaurus |
+
+---
+
 ## What to build (in order)
 
 ### Phase 1: Foundation