​

Component Library Architecture

​

1. Architecture Overview

​

1.1 Core Architecture

​

1.2 Architectural Principles

1. Domain-Driven Organization: Components organized by business domain first
2. Component Composition: Complex components built by composing simpler ones
3. Separation of Concerns: Logic separated from presentation
4. Accessibility: WCAG 2.1 AA standards throughout
5. Performance: Server-first approach with selective client components
6. Maintainability: Clear documentation and testing
7. Reusability: Components designed for reuse across domains

​

1.3 Domain Organization

/components
├── marketing/       # Landing page components
├── marketplace/     # Builder discovery components
├── profile/         # User profile components
├── trust/           # Trust indicators
├── booking/         # Scheduling components
├── payment/         # Payment processing
├── learning/        # Learning experience
├── community/       # Community features
├── ui/              # Shared UI components
└── providers/       # Context providers

​

2. Component Categories

​

2.1 Visual Components

1. Marketing Components: Landing page elements (header, hero, CTA)
2. Marketplace Components: Builder cards, grids, and discovery interfaces
3. Profile Components: Profile headers, cards, and information displays
4. Trust Components: Validation badges, testimonials, and trust indicators

​

2.2 Interactive Components

1. Form Components: Inputs, selects, checkboxes, validation
2. Navigation Components: Tabs, accordions, dropdowns, menus
3. Overlay Components: Modals, dialogs, popovers, tooltips
4. Selection Components: Date pickers, time selectors, multi-select

​

2.3 Component Hierarchy

Page Components
    │
    ▼
Domain Components
    │
    ▼
Shared UI Components
    │
    ▼
Base Components (Magic UI Pro)

​

3. Magic UI Pro Integration

​

3.1 Integration Approach

pnpm dlx shadcn@latest add "https://magicui.design/r/[component].json"

​

3.2 Component Customization

1. Tailwind Utilities: Apply Tailwind classes for styling
2. Props Configuration: Modify behavior through component props
3. Theme Configuration: Adjust theme variables in Tailwind config
4. Component Extension: Create new components that extend Magic UI

​

3.3 Priority Magic UI Components

​

4. State Management

​

4.1 State Management Approach

1. Local Component State: useState for component-specific state
2. React Context: For shared state across component trees
3. Custom Hooks: For encapsulating reusable state logic
4. Form Library: react-hook-form with Zod for validation

​

4.2 Key State Patterns

1. Container/Presenter Pattern: Separate logic from presentation
2. Lifting State Up: Parent components manage shared state
3. Derived State: Calculate state from props/state with useMemo
4. Context Providers: Domain-specific context providers

​

5. Component Implementation

​

5.1 Implementation Timeline

​

5.2 Component Implementation Priorities

1. Landing Page: Marketing components - fastest path to value
2. Marketplace: Builder discovery components - critical for revenue
3. Liam’s Profile: Profile components - essential for booking
4. Booking System: Calendar and form components - revenue generation

​

5.3 Testing Strategy

1. Unit Testing: Component functionality and props
2. Integration Testing: Component interactions
3. Accessibility Testing: WCAG 2.1 AA compliance
4. Visual Testing: Component appearance and responsiveness

​

6. Type System Integration

​

6.1 Standardized Component Props

// All components extend base interfaces
export interface ComponentProps extends 
  BaseComponentProps,
  WithChildrenProps,
  DisableableProps {
  // Component-specific props
}

​

6.2 Component Type Patterns

1. UI Components: Extend base interfaces with variant support
2. Domain Components: Include domain-specific data types
3. Polymorphic Components: Support multiple element types
4. Loading States: Consistent skeleton UI patterns

​

6.3 Variant System

export type StandardSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
export type ButtonVariant = 'default' | 'primary' | 'secondary' | 'destructive';

​

7. Code Quality and Standards

1. TypeScript: Strict typing for all component props and state using standardized interfaces
2. JSDoc: Documentation for all components and their props
3. Storybook: Visual documentation and testing
4. Automated Tests: Unit and integration tests with high coverage
5. CI/CD: Automated testing and deployment workflows
6. Type Safety: Zero TypeScript errors in component implementations

​

See Also

• TypeScript Type System
• Visual Components
• Interactive Components
• Component Style Guide
• Marketplace Components