vibn-frontend/LAYOUT-ARCHITECTURE.md

🏗️ 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:

<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:

<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

// 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:

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