metabuilder/frontends/nextjs/src/components

MetaBuilder Component Architecture

This directory contains all React components for MetaBuilder, organized using Atomic Design principles.

Quick Links

• 📖 Full Atomic Design Guide
• 🗺️ Complete Component Map
• 📊 Visual Structure Diagram
• 🚀 Quick Start Guide

Directory Structure

components/
├── atoms/              → Basic UI elements (12+ from shadcn/ui)
├── molecules/          → Simple composites (6 components)
├── organisms/          → Complex features (40+ components)
├── ui/                 → shadcn components (unchanged)
├── shared/             → Shared utilities
├── level1/             → Level 1 page sections
├── level2/             → Level 2 page sections
├── level4/             → Level 4 page sections
├── level5/             → Level 5 page sections
└── [Level1-5].tsx     → Top-level page components

Quick Import Reference

// Atoms (basic UI elements)
import { Button, Input, Label, Badge } from '@/components/atoms'

// Molecules (simple composites)
import { AppHeader, ProfileCard } from '@/components/molecules'

// Organisms (complex features)
import { ComponentCatalog, SchemaEditor } from '@/components/organisms'

// Pages
import Level4 from '@/components/Level4'

Component Categories

🔹 Atoms (Basic UI)

Small, indivisible UI elements:

• Button, Input, Label, Badge, Avatar
• Separator, Skeleton, Switch, Slider
• Progress, Checkbox, RadioGroup

When to use: Never create custom atoms unless shadcn doesn't provide it.

🔸 Molecules (Simple Composites)

Groups of 2-5 atoms with focused purpose:

• AppHeader, AppFooter
• GodCredentialsBanner, ProfileCard
• SecurityWarningDialog, PasswordChangeDialog

When to use: When combining 2-5 atoms for a reusable component.

🔶 Organisms (Complex Features)

Full-featured sections with business logic:

Builders: Builder, Canvas, ComponentCatalog, PropertyInspector

Editors: SchemaEditor, CodeEditor, JsonEditor, NerdModeIDE

NerdModeIDE is a thin wrapper that re-exports the modular implementation under components/nerd-mode-ide/.

Managers: DatabaseManager, UserManagement, PackageManager, ThemeEditor

Features: IRCWebchat, WorkflowEditor, AuditLogViewer, ScreenshotAnalyzer

When to use: For complex, feature-complete sections with state and logic.

📄 Pages (Complete Views)

Top-level page components:

• Level1 - Public landing page
• Level2 - User dashboard
• Level3 - Admin panel
• Level4 - God builder
• Level5 - Super God panel

When to use: Only for complete page views.

Rules

✅ Allowed Dependencies

• Atoms → React, external libraries only
• Molecules → Atoms
• Organisms → Atoms, Molecules, other Organisms
• Pages → Atoms, Molecules, Organisms

❌ Forbidden Dependencies

• Atoms ❌ Molecules, Organisms
• Molecules ❌ Organisms

Creating New Components

1. Determine Category

Ask yourself:

• Is it a single UI element? → Use an existing Atom (shadcn)
• Is it 2-5 atoms together? → Create a Molecule
• Is it a complex feature? → Create an Organism
• Is it a full page? → Create a Page

2. Create the Component

Example Molecule:

// src/components/molecules/StatusIndicator.tsx
import { Badge, Avatar } from '@/components/atoms'

export function StatusIndicator({ user, status }: StatusIndicatorProps) {
  return (
    <div className="flex items-center gap-2">
      <Avatar src={user.avatar} />
      <Badge>{status}</Badge>
    </div>
  )
}

Example Organism:

// src/components/organisms/CommentSection.tsx
import { useState } from 'react'
import { useKV } from '@/hooks/data/useKV'
import { Button, Input } from '@/components/atoms'
import { ProfileCard } from '@/components/molecules'

export function CommentSection({ postId }: CommentSectionProps) {
  const [comments, setComments] = useKV(`comments-${postId}`, [])
  const [text, setText] = useState('')
  
  const addComment = () => {
    setComments(current => [...current, { text, timestamp: Date.now() }])
    setText('')
  }
  
  return (
    <div className="space-y-4">
      <Input value={text} onChange={(e) => setText(e.target.value)} />
      <Button onClick={addComment}>Add Comment</Button>
      {comments.map(comment => (
        <ProfileCard key={comment.timestamp} comment={comment} />
      ))}
    </div>
  )
}

3. Add to Index File

// src/components/molecules/index.ts
export { StatusIndicator } from './StatusIndicator'

// src/components/organisms/index.ts
export { CommentSection } from './CommentSection'

4. Document if Complex

Add JSDoc comments for complex organisms:

/**
 * CommentSection provides a full commenting system with real-time updates.
 * 
 * @param postId - The post to display comments for
 * @param allowReplies - Enable nested comment replies
 */
export function CommentSection({ postId, allowReplies }: Props) {
  // ...
}

Benefits

🎯 For Developers

• Clear hierarchy - Know where to find components
• Easy testing - Test smaller pieces in isolation
• Faster development - Reuse existing atoms/molecules
• Better maintainability - Changes propagate naturally

🎨 For Designers

• Consistent UI - Shared atoms ensure visual consistency
• Living design system - Components serve as documentation
• Easy prototyping - Compose features from existing parts

📚 For Documentation

• Self-documenting - Structure explains complexity
• Easy onboarding - New developers understand quickly
• Clear guidelines - Know where new components belong

Testing Strategy

Unit Tests (Atoms & Molecules)

test('ProfileCard displays user info', () => {
  render(<ProfileCard user={mockUser} />)
  expect(screen.getByText(mockUser.name)).toBeInTheDocument()
})

Integration Tests (Organisms)

test('CommentSection allows adding comments', async () => {
  render(<CommentSection postId="123" />)
  await userEvent.type(screen.getByRole('textbox'), 'Great post!')
  await userEvent.click(screen.getByText('Add Comment'))
  expect(screen.getByText('Great post!')).toBeInTheDocument()
})

E2E Tests (Pages)

test('Level2 user dashboard works', async () => {
  await page.goto('/level2')
  await page.click('text=Profile')
  expect(page.locator('.profile-card')).toBeVisible()
})

Migration Notes

This structure is implemented using virtual organization via index.ts exports.

• ✅ Existing imports continue to work
• ✅ New code can use atomic imports
• ✅ No breaking changes
• ✅ Gradual migration possible

Old Way (still works)

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

New Way (recommended)

import { Button } from '@/components/ui'
import { ComponentCatalog } from '@/components/organisms'

Component Count

• Atoms: 12+ (all from shadcn/ui)
• Molecules: 6 components
• Organisms: 40+ components
• Pages: 5 components
• Total: 60+ components

Common Patterns

Pattern: Form Field

// Molecule combining Label + Input + Error
import { Label, Input } from '@/components/atoms'

export function FormField({ label, error, ...props }: FormFieldProps) {
  return (
    <div>
      <Label>{label}</Label>
      <Input {...props} />
      {error && <span className="text-destructive">{error}</span>}
    </div>
  )
}

Pattern: Data List

// Organism handling data fetching and display
import { useKV } from '@/hooks/data/useKV'
import { Button } from '@/components/atoms'
import { Card } from '@/components/ui'

export function UserList() {
  const [users] = useKV('users', [])
  return (
    <Card>
      {users.map(user => (
        <div key={user.id}>{user.name}</div>
      ))}
    </Card>
  )
}

Pattern: Feature Section

// Organism composing molecules and atoms
import { Button, Input } from '@/components/atoms'
import { ProfileCard } from '@/components/molecules'

export function UserProfile({ userId }: UserProfileProps) {
  // Complex business logic here
  return (
    <div>
      <ProfileCard user={user} />
      <Input />
      <Button>Save</Button>
    </div>
  )
}

Need Help?

• Finding components: Check COMPONENT_MAP.md
• Understanding structure: Read ATOMIC_DESIGN.md
• Getting started: See ATOMIC_QUICKSTART.md
• Visual reference: View ATOMIC_STRUCTURE.md

Resources

• Atomic Design by Brad Frost
• shadcn/ui Documentation
• React Component Patterns

---

Remember: Atoms → Molecules → Organisms → Pages

Build from the bottom up, compose from small to large! 🎨