# 🏗️ Layout Architecture - Plane.so Inspired

## Overview

The frontend uses a **4-column layout** inspired by Plane.so, providing a sophisticated and organized interface for managing AI-powered development projects.

## Layout Structure

```
┌────────┬──────────────┬─────────────────────────┬──────────────┐
│  LEFT  │   PROJECT    │     MAIN CONTENT        │    RIGHT     │
│  RAIL  │   SIDEBAR    │                         │    PANEL     │
│        │              │  [Header/Breadcrumbs]   │              │
│  60px  │   250px      │                         │    300px     │
│        │  resizable   │  [Page Content]         │  collapsible │
│        │              │                         │              │
└────────┴──────────────┴─────────────────────────┴──────────────┘
```

## Components

### 1. **Left Rail** (`components/layout/left-rail.tsx`)

**Purpose:** App-level navigation

**Features:**
- Workspace avatar/switcher
- Major app sections (Projects, Wiki, AI)
- Settings & Help
- User profile
- Fixed width: 60px

**Sections:**
- 🗂️ **Projects** - Project management (currently selected)
- 📖 **Wiki** - Documentation & knowledge base
- ✨ **AI** - AI assistant & chat
- ⚙️ **Settings** - App settings
- ❓ **Help** - Help & support

---

### 2. **Project Sidebar** (`components/layout/project-sidebar.tsx`)

**Purpose:** Project-specific navigation

**Features:**
- List of all projects (expandable tree)
- Project search
- "New work item" button
- Per-project navigation (Overview, Sessions, Features, etc.)
- Resizable (200px - 500px)
- Drag handle on right edge

**Project Views:**
- 📊 **Overview** - Project dashboard
- 💬 **Sessions** - AI coding sessions
- 📦 **Features** - Feature planning & tracking
- 🗺️ **API Map** - API endpoint documentation
- 🏗️ **Architecture** - Architecture docs & ADRs
- 📈 **Analytics** - Token usage, costs, metrics

**Current Projects:**
1. 🤖 AI Proxy
2. 🌐 VIBN Website
3. ⚛️ VIBN Frontend

---

### 3. **Main Content** (`app/(dashboard)/[projectId]/*`)

**Purpose:** Primary content area

**Features:**
- Page header with breadcrumbs
- Dynamic content based on current route
- Full-width layout
- Scrollable content area

**Header Components:**
- Breadcrumb navigation (e.g., "🤖 AI Proxy > Overview")
- Action buttons (e.g., Info, Share, Export)

---

### 4. **Right Panel** (`components/layout/right-panel.tsx`)

**Purpose:** Contextual information & AI interaction

**Features:**
- Collapsible (clicks to 48px icon bar)
- Tabbed interface
- Fixed width: 320px when expanded

**Tabs:**

#### **Activity Feed**
- Real-time project updates
- Team member activity
- Work completed notifications
- Deployment status
- Empty state: "Enable project grouping"

#### **AI Chat**
- Persistent AI assistant
- Project-specific context
- Ask questions about:
  - Current codebase
  - Architecture decisions
  - Token usage & costs
  - Documentation generation
- Press Enter to send, Shift+Enter for new line

---

## Implementation Details

### App Shell (`components/layout/app-shell.tsx`)

The main container that orchestrates all four columns:

```tsx
<div className="flex h-screen w-full overflow-hidden">
  <LeftRail />
  <ProjectSidebar projectId={projectId} />
  <main className="flex-1 flex flex-col overflow-hidden">
    {children} {/* Page content + PageHeader */}
  </main>
  <RightPanel />
</div>
```

### Page Header (`components/layout/page-header.tsx`)

Consistent header for all pages:

```tsx
<PageHeader
  projectId="ai-proxy"
  projectName="AI Proxy"
  projectEmoji="🤖"
  pageName="Overview"
/>
```

---

## Responsive Behavior

### Desktop (> 1280px)
- All 4 columns visible
- Project sidebar resizable
- Right panel collapsible

### Tablet (768px - 1280px)
- Left rail hidden (hamburger menu)
- Project sidebar collapsible
- Main content full width
- Right panel hidden by default

### Mobile (< 768px)
- Single column layout
- Drawer navigation for all sidebars
- Full-screen content
- AI chat as bottom sheet

---

## Key Design Decisions

### Why 4 Columns?

1. **Left Rail:** Separates app-level from project-level navigation
2. **Project Sidebar:** Allows multi-project management without losing context
3. **Main Content:** Dedicated space for primary work
4. **Right Panel:** Keeps contextual info & AI always accessible

### Inspired by Plane.so

- ✅ Clean, minimal design
- ✅ Resizable panels for customization
- ✅ Tree navigation for projects
- ✅ Breadcrumb-based header
- ✅ Persistent activity feed
- ✅ Professional UI components (shadcn/ui)

### Differences from Plane

- **AI Chat:** We added a dedicated AI assistant tab
- **Real-time Data:** Direct PostgreSQL integration
- **Token Analytics:** Built-in cost tracking
- **Session History:** AI conversation tracking

---

## Component Hierarchy

```
app/layout.tsx (Root)
  └─ (dashboard)/[projectId]/layout.tsx
      └─ AppShell
          ├─ LeftRail
          ├─ ProjectSidebar
          ├─ Main
          │   ├─ PageHeader
          │   └─ Page Content (overview, sessions, etc.)
          └─ RightPanel
              ├─ Activity Tab
              └─ AI Chat Tab
```

---

## Future Enhancements

### Planned Features

1. **Real-time Updates**
   - WebSocket connection for live activity feed
   - AI chat responses streaming
   - Session updates

2. **Customization**
   - Save panel widths per user
   - Theme switching (dark/light/custom)
   - Layout presets (focus, review, chat)

3. **Collaboration**
   - Multi-user presence indicators
   - Shared cursors in AI chat
   - @mentions in activity feed

4. **AI Enhancements**
   - Code suggestions in right panel
   - Inline documentation lookup
   - Architecture diagram generation

---

## Usage

### Adding a New Page

1. Create page in `app/(dashboard)/[projectId]/your-page/page.tsx`
2. Add PageHeader component
3. Add route to ProjectSidebar menu items
4. Page automatically inherits 4-column layout

```tsx
// your-page/page.tsx
import { PageHeader } from "@/components/layout/page-header";

export default async function YourPage({ params }: { params: { projectId: string } }) {
  return (
    <>
      <PageHeader
        projectId={params.projectId}
        projectName="AI Proxy"
        projectEmoji="🤖"
        pageName="Your Page"
      />
      <div className="flex-1 overflow-auto p-6">
        {/* Your content here */}
      </div>
    </>
  );
}
```

### Customizing Sidebar

Edit `components/layout/project-sidebar.tsx`:

```typescript
const menuItems = [
  {
    title: "Your New Section",
    icon: YourIcon,
    href: "/your-route",
  },
  // ... existing items
];
```

---

## Tech Stack

- **Framework:** Next.js 15 (App Router)
- **Styling:** Tailwind CSS 4.0
- **Components:** shadcn/ui
- **Icons:** Lucide React
- **Database:** PostgreSQL (Railway)
- **State:** React Server Components + Client Components
- **Type Safety:** TypeScript

---

## Performance Considerations

- Server components for static layouts
- Client components only where interactivity needed
- Optimistic UI updates for real-time feel
- Lazy loading for right panel content
- Virtual scrolling for long lists

---

**Status:** ✅ Implemented & Running on `http://localhost:3000`