lovable-boilerplate architecture.instructions.md

Code Architecture & Reusability Guidelines

CRITICAL ARCHITECTURE RULES

NEVER CREATE:

• Components over 300 lines
• Duplicate logic across components
• Inline API calls in UI components
• Mixed concerns (UI + business logic + API)
• Copy-pasted code blocks

ALWAYS CREATE:

• Single-responsibility components (20-100 lines)
• Custom hooks for reusable logic
• Service layer for API calls
• Shared types in lib/types.ts
• Composition patterns from smaller components

Component Composition Over Monoliths

NEVER create large, monolithic components that handle multiple concerns: Avoid: Single components or page that exceed 300 lines or handle multiple responsibilities Avoid: Pages that contain all logic inline instead of using smaller components Avoid: Components that mix UI rendering, business logic, and API calls

ALWAYS break down complex functionality into smaller, reusable pieces: Create: Focused components with single responsibilities (20-100 lines) Create: Composition patterns using multiple small components Create: Custom hooks for reusable logic extraction Create: Separate layers for data fetching, business logic, and presentation

Component Organization Strategy

1. Feature-Based Organization

// Wrong: Everything in one file
const Dashboard = () => {
  // 300+ lines of mixed logic
  return <div>{/* massive JSX */}</div>
}

// ✅ Correct: Composed from focused components
const Dashboard = () => (
  <DashboardLayout>
    <DashboardHeader />
    <DashboardStats />
    <DashboardCharts />
    <DashboardActivity />
  </DashboardLayout>
)

2. Reusable Component Patterns

// ✅ Base components for consistent UI patterns
const Card = ({ children, className, ...props }) => (
  <div className={cn("rounded-lg border bg-card", className)} {...props}>
    {children}
  </div>
)

// ✅ Composite components for complex patterns  
const StatsCard = ({ title, value, change, icon: Icon }) => (
  <Card className="p-6">
    <div className="flex items-center justify-between">
      <div>
        <p className="text-sm text-muted-foreground">{title}</p>
        <p className="text-2xl font-bold">{value}</p>
        <p className="text-sm text-green-600">{change}</p>
      </div>
      <Icon className="h-8 w-8 text-muted-foreground" />
    </div>
  </Card>
)