Application Architecture

Best practices for building scalable and maintainable UI components.

Component-Based Design

Break down the UI into small, reusable components.

Each component should have a single responsibility. This makes the code easier to understand, test, and reuse. It also allows the AI to make more targeted and accurate changes.

Good Example


// GOOD: A reusable, props-based component
// File: /components/ui/custom-button.tsx

import { Button } from '@/components/ui/button';

interface CustomButtonProps {
  label: string;
  variant: 'primary' | 'secondary';
  onClick: () => void;
}

export function CustomButton({ label, variant, onClick }: CustomButtonProps) {
  return (
    <Button 
      onClick={onClick}
      className={variant === 'primary' ? 'bg-blue-500' : 'bg-gray-500'}
    >
      {label}
    </Button>
  );
}

Bad Example


// BAD: A non-reusable, hardcoded component
// Found inside another page file

function MySpecialButton() {
    const handleClick = () => {
        console.log("Button was clicked!");
    }

    return (
        <button 
            onClick={handleClick}
            className="bg-blue-500 text-white p-2 rounded"
        >
            Click Me
        </button>
    )
}

Clear Naming Conventions

Use descriptive names for files, components, and props.

Descriptive names provide context, making it easier for both humans and AI to understand the code's purpose. For example, a file named UserProfileCard.tsx is much clearer than Card.tsx.

Props for Configuration

Use props to pass data and configuration to components.

Avoid hardcoding values inside components. Instead, pass them down as props. This makes components more flexible and reusable across different parts of the application. The AI can easily modify props to change a component's appearance or behavior without needing to understand its internal logic.

Use ShadCN/UI Components

Leverage the existing component library for consistency.

This application is built with ShadCN/UI. Using these pre-built components for elements like buttons, cards, and forms ensures visual consistency and accelerates development. The AI is familiar with this library and can work with it effectively.

File & Directory Structure

A logical folder structure improves navigation and maintainability.

A well-organized project is easier for everyone (including the AI) to understand. This project follows a standard structure:

/src/app: Contains all routes and pages, following Next.js App Router conventions.
/src/components: Home to all reusable React components. UI primitives are in /ui, while larger, domain-specific components are in /landing or /dashboard.
/src/lib: Utility functions, configuration, and shared logic reside here.
/src/ai: Holds all Genkit flows and AI-related logic.

Styling with Tailwind CSS

Use theme variables for a consistent design system.

All styling should be done using Tailwind CSS utility classes. For colors, always use the CSS variables defined in src/app/globals.css (e.g., bg-background, text-primary). Avoid using arbitrary color values (e.g., text-red-500) to ensure the application theme can be updated centrally.