310 lines
7.4 KiB
Markdown
310 lines
7.4 KiB
Markdown
# 🏗️ 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`
|
|
|