# 🎨 Frontend Structure - Complete Map

**App URL:** http://localhost:3000

---

## 🗺️ **Main Navigation Structure**

```
/[workspace]/                           # Workspace-level pages
├── /projects                           # Projects list
├── /project/[projectId]/               # Individual project pages
├── /connections                        # GitHub/API connections
├── /keys                              # API key management
└── /new-project/new                   # Create new project
```

---

## 📱 **Core Pages (Active & Working)**

### **1. AI Chat** ✅
```
/[workspace]/project/[projectId]/v_ai_chat
```
**File:** `app/[workspace]/project/[projectId]/v_ai_chat/page.tsx`

**Features:**
- ✅ Real-time chat with AI (6 modes)
- ✅ **Vector search integration** (retrieves from AlloyDB)
- ✅ Conversation history (Firestore)
- ✅ "Analyze Context" button (batch extraction)
- ✅ Mode badge showing current AI mode
- ✅ Artifacts badge (shows what AI is using)
- ✅ File attachments (not yet wired to backend)

**What AI Can Access:**
- Knowledge items (documents, AI chats)
- Vector search (50 chunks from AlloyDB)
- GitHub repo analysis
- Product model, MVP plan, Marketing plan
- Extractions

---

### **2. Context Management** ✅
```
/[workspace]/project/[projectId]/context
```
**File:** `app/[workspace]/project/[projectId]/context/page.tsx`

**Features:**
- ✅ Upload documents
- ✅ Connect GitHub repos
- ✅ Import AI chat transcripts (hidden per your request)
- ✅ View all connected sources
- ✅ See document summaries

**What Happens:**
1. Upload doc → Firestore + AlloyDB chunking
2. Connect GitHub → Repo analysis + tree view
3. Everything becomes searchable by AI

---

### **3. Code Viewer** ✅
```
/[workspace]/project/[projectId]/code
```
**File:** `app/[workspace]/project/[projectId]/code/page.tsx`

**Features:**
- ✅ Browse connected GitHub repo
- ✅ File tree navigation
- ✅ View file contents with syntax highlighting
- ✅ Line numbers
- ⚠️ AI can reference but not directly read files yet

---

### **4. Projects List** ✅
```
/[workspace]/projects
```
**File:** `app/[workspace]/projects/page.tsx`

**Features:**
- ✅ View all projects
- ✅ Create new project
- ✅ Filter/search projects
- ✅ Quick actions

---

### **5. Project Overview** ✅
```
/[workspace]/project/[projectId]/overview
```
**File:** `app/[workspace]/project/[projectId]/overview/page.tsx`

**Features:**
- ✅ Project stats
- ✅ Recent activity
- ✅ Phase progress
- ✅ Quick access to sections

---

### **6. Connections** ✅
```
/[workspace]/connections
```
**File:** `app/[workspace]/connections/page.tsx`

**Features:**
- ✅ GitHub OAuth integration
- ✅ Connect/disconnect repos
- ✅ View connected accounts

---

### **7. Vision Page** ✅
```
/[workspace]/project/[projectId]/vision
```
**File:** `app/[workspace]/project/[projectId]/vision/page.tsx`

**Features:**
- ✅ View canonical product model
- ✅ See vision artifacts
- ⚠️ Currently read-only (no editing UI yet)

---

## 🚧 **Pages with Placeholder UI**

These exist but show mock/placeholder data:

### **Design System** 🔨
```
/[workspace]/project/[projectId]/design
```
**File:** `app/[workspace]/project/[projectId]/design/page.tsx`

**Status:** Mock UI (not connected to backend)
- Shows placeholder screens
- Design variation concepts
- Not integrated with AI yet

### **API Map** 🔨
```
/[workspace]/project/[projectId]/api-map
```
**Status:** Mock UI
- Placeholder API endpoints
- Not generated from actual data

### **Architecture** 🔨
```
/[workspace]/project/[projectId]/architecture
```
**Status:** Mock UI
- Placeholder architecture diagrams
- Not AI-generated yet

### **Features** 🔨
```
/[workspace]/project/[projectId]/features
```
**Status:** Mock UI
- Placeholder feature list
- Not synced with MVP plan

### **Plan** 🔨
```
/[workspace]/project/[projectId]/plan
```
**Status:** Mock UI
- Shows placeholder tasks
- Not connected to MVP plan data

### **Progress** 🔨
```
/[workspace]/project/[projectId]/progress
```
**Status:** Mock UI
- Placeholder progress tracking

### **Deployment** 🔨
```
/[workspace]/project/[projectId]/deployment
```
**Status:** Mock UI
- Placeholder deployment info

### **Automation** 🔨
```
/[workspace]/project/[projectId]/automation
```
**Status:** Mock UI
- Placeholder automation workflows

### **Analytics** 🔨
```
/[workspace]/project/[projectId]/analytics
```
**Status:** Mock UI
- Placeholder analytics dashboards

### **Sessions** 🔨
```
/[workspace]/project/[projectId]/sessions
```
**Status:** Mock UI
- Placeholder work sessions

---

## 🎯 **Layout Components**

### **Main Layout**
```typescript
app/[workspace]/project/[projectId]/layout.tsx
```

**Structure:**
```
┌─────────────────────────────────────────┐
│  Workspace Left Rail                    │
├──────────┬──────────────────────────────┤
│ Project  │  Main Content Area           │
│ Sidebar  │  (Your active page)          │
│          │                              │
│          │                              │
└──────────┴──────────────────────────────┘
```

**Features:**
- Persistent left rail (workspace navigation)
- Project sidebar (section navigation)
- Toast notifications (Sonner)

---

## 🔗 **Key UI Components**

### **WorkspaceLeftRail**
```
components/layout/workspace-left-rail.tsx
```
**Navigation:**
- Projects
- Connections
- Keys
- MCP (Model Context Protocol)

### **ProjectSidebar**
```
components/layout/project-sidebar.tsx
```
**Sections:**
- Overview
- AI Chat ✅
- Context ✅
- Code ✅
- Vision ✅
- Plan 🔨
- Design 🔨
- Features 🔨
- API Map 🔨
- Architecture 🔨
- Progress 🔨
- Analytics 🔨
- Deployment 🔨
- Automation 🔨
- Sessions 🔨
- Settings

### **RightPanel**
```
components/layout/right-panel.tsx
```
**Features:**
- Quick AI chat access (collapsed by default)
- Context-aware to current project
- ⚠️ Currently not implemented (references only)

---

## 🎨 **UI Library**

Using **shadcn/ui** components:
- `Card`, `Button`, `Input`, `Textarea`
- `Dialog`, `Sheet`, `Tabs`, `Badge`
- `Dropdown`, `Select`, `Tooltip`
- `Toast` notifications (Sonner)

**Styling:**
- Tailwind CSS
- Dark mode ready (not enabled)
- Responsive (mobile not optimized yet)

---

## 📊 **Data Flow**

```
Frontend Pages
    ↓
API Routes (/app/api/*)
    ↓
Server Helpers (/lib/server/*)
    ↓
Databases:
    ├─ Firestore (metadata, chat history, projects)
    ├─ AlloyDB (vector chunks for search)
    └─ Firebase Storage (uploaded files)
    ↓
AI Services:
    ├─ Gemini (chat, extraction, embeddings)
    └─ GitHub API (repo analysis)
```

---

## ✅ **What's Fully Working**

1. **AI Chat** - Complete with vector search
2. **Context Management** - Upload, connect, view
3. **Code Viewer** - Browse GitHub repos
4. **GitHub Integration** - OAuth, repo connection
5. **Document Upload** - With AlloyDB chunking
6. **Conversation History** - Persists across refreshes
7. **Batch Extraction** - "Analyze Context" button
8. **Mode-Based AI** - 6 modes with smart routing

---

## 🚧 **What Needs Work**

### **High Priority:**
1. **Vision Page** - Make it editable, not just read-only
2. **Plan Page** - Connect to actual MVP plan data
3. **Features Page** - Sync with canonicalProductModel
4. **RightPanel AI Chat** - Implement collapsed quick access

### **Medium Priority:**
5. **Design Page** - Generate actual design suggestions
6. **API Map Page** - Generate from product model
7. **Architecture Page** - AI-generated architecture
8. **Progress Page** - Real task tracking

### **Low Priority:**
9. **Analytics** - Usage tracking
10. **Deployment** - Deployment tracking
11. **Automation** - Workflow automation
12. **Sessions** - Work session tracking

---

## 🎯 **Recommended Focus**

**For immediate user value:**
1. ✅ AI Chat with vector search (DONE!)
2. ✅ Context upload & management (DONE!)
3. ✅ GitHub integration (DONE!)
4. 🔨 **Vision Page editing** - Let users refine product model
5. 🔨 **Plan Page with real data** - Show actual MVP plan

**The core loop works:**
```
Upload context → AI analyzes → Chat with AI → Get answers
                                    ↓
                            (grounded in your docs)
```

Everything else is **enhancement** on top of this working foundation! 🚀

---

## 🔗 **Quick Links**

- **Start AI Chat:** http://localhost:3000/marks-account/project/YOUR_PROJECT_ID/v_ai_chat
- **Upload Context:** http://localhost:3000/marks-account/project/YOUR_PROJECT_ID/context
- **View Code:** http://localhost:3000/marks-account/project/YOUR_PROJECT_ID/code
- **Projects List:** http://localhost:3000/marks-account/projects

Replace `YOUR_PROJECT_ID` with `4QzuyYxmvDfV6YB9kwtJ` (your current project).

