VIBN Frontend for Coolify deployment
This commit is contained in:
309
LAYOUT-ARCHITECTURE.md
Normal file
309
LAYOUT-ARCHITECTURE.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# 🏗️ 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`
|
||||
|
||||
Reference in New Issue
Block a user