metabuilder/docs/implementation/COMPONENT_MAP.md

Component Classification Map

This document provides a complete mapping of all components in MetaBuilder organized by atomic design principles.

Directory Structure

src/components/
├── atoms/                    # Basic UI elements (shadcn/ui exports)
│   ├── index.ts             # Re-exports shadcn components
│   └── README.md
├── molecules/               # Simple composite components
│   ├── index.ts
│   ├── README.md
│   ├── AppHeader.tsx        → from shared/
│   ├── AppFooter.tsx        → from shared/
│   ├── GodCredentialsBanner.tsx → from level1/
│   ├── ProfileCard.tsx      → from level2/
│   ├── SecurityWarningDialog.tsx
│   └── PasswordChangeDialog.tsx
├── organisms/               # Complex feature components
│   ├── index.ts
│   ├── README.md
│   └── [all complex components - see below]
├── ui/                      # shadcn components (unchanged)
├── shared/                  # Shared utilities (keep existing)
├── level1/                  # Level 1 page components
├── level2/                  # Level 2 page components
├── level4/                  # Level 4 page components
├── level5/                  # Level 5 page components
└── [Level components]       # Top-level page components

Atoms (Basic UI Elements)

All atoms are from shadcn/ui and re-exported via @/components/atoms:

Component	Source	Purpose
Button	shadcn/ui	Clickable button element
Input	shadcn/ui	Text input field
Label	shadcn/ui	Form label
Badge	shadcn/ui	Status/tag indicator
Avatar	shadcn/ui	User avatar image
Separator	shadcn/ui	Visual divider
Skeleton	shadcn/ui	Loading placeholder
Switch	shadcn/ui	Toggle switch
Slider	shadcn/ui	Range slider
Progress	shadcn/ui	Progress bar
Checkbox	shadcn/ui	Checkbox input
RadioGroup	shadcn/ui	Radio buttons

Note: All other shadcn components (Card, Dialog, Tabs, Select, etc.) should be imported directly from @/components/ui/* as needed.

Molecules (Simple Composites)

Component	Current Location	Complexity	Description
AppHeader	shared/	Low	Header with logo and navigation
AppFooter	shared/	Low	Footer with links
GodCredentialsBanner	level1/	Low	Alert banner for credentials
ProfileCard	level2/	Low	User profile card display
SecurityWarningDialog	root	Medium	Security warning modal
PasswordChangeDialog	root	Medium	Password change form

Organisms (Complex Features)

Core Builders

Component	Current Location	Purpose
Builder	root	Visual page builder system
Canvas	root	Rendering canvas for builder
ComponentCatalog	root	Component selection interface
ComponentConfigDialog	root	Component configuration modal
ComponentHierarchyEditor	root	Component tree editor
PropertyInspector	root	Property editing panel

Schema & Data Management

Component	Current Location	Purpose
SchemaEditor	root	Schema editing with Monaco
SchemaEditorLevel4	root	Level 4 schema editor variant
DatabaseManager	root	Database operations panel
FieldRenderer	root	Dynamic field renderer
RecordForm	root	Record CRUD form
ModelListView	root	Model list display

Code Editors

Component	Current Location	Purpose
CodeEditor	root	Monaco-based code editor
JsonEditor	root	JSON editing interface
LuaEditor	root	Lua script editor
LuaSnippetLibrary	root	Lua snippet management
NerdModeIDE	root	Full IDE panel

Configuration Managers

Component	Current Location	Purpose
CssClassBuilder	root	Visual CSS selector
CssClassManager	root	CSS class library manager
DropdownConfigManager	root	Dropdown configuration
ThemeEditor	root	Theme customization
SMTPConfigEditor	root	SMTP settings form
GodCredentialsSettings	root	God credentials manager
PageRoutesManager	root	Page routing config

Package System

Component	Current Location	Purpose
PackageManager	root	Package browsing/install
PackageImportExport	root	Import/export packages

User & Auth

Component	Current Location	Purpose
UserManagement	root	User CRUD interface
UnifiedLogin	root	Unified authentication
Login	root	Login form

Features & Tools

Component	Current Location	Purpose
IRCWebchat	root	IRC chat interface
IRCWebchatDeclarative	root	Declarative IRC chat
WorkflowEditor	root	Workflow configuration
AuditLogViewer	root	Audit log display
ScreenshotAnalyzer	root	Screenshot analysis
GitHubActionsFetcher	root	GitHub actions integration

Page Components

Component	Current Location	Purpose
GenericPage	root	Generic page renderer
RenderComponent	root	Dynamic component renderer
QuickGuide	root	Feature guide/docs

Level Sections

Component	Current Location	Purpose
HeroSection	level1/	Landing hero section
FeaturesSection	level1/	Features showcase
ContactSection	level1/	Contact form
NavigationBar	level1/	Main navigation
CommentsList	level2/	Comments list

Pages (Top-Level)

These remain at component root level:

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

Import Path Changes

Before (current)

import { ComponentCatalog } from '@/components/ComponentCatalog'
import { PropertyInspector } from '@/components/PropertyInspector'
import { AppHeader } from '@/components/shared/AppHeader'

After (with atomic structure)

// Atoms (shadcn components)
import { Button, Input, Label } from '@/components/atoms'

// Molecules
import { 
  AppHeader, 
  ProfileCard, 
  SecurityWarningDialog 
} from '@/components/molecules'

// Organisms
import { 
  ComponentCatalog, 
  PropertyInspector,
  SchemaEditor 
} from '@/components/organisms'

// Pages (unchanged)
import Level1 from '@/components/Level1'

Benefits of This Structure

1. Clear Hierarchy - Instantly understand component complexity
2. Better Reusability - Atoms and molecules are highly reusable
3. Easier Testing - Test atoms/molecules in isolation
4. Improved Onboarding - New developers understand architecture quickly
5. Maintainability - Changes to atoms propagate naturally
6. Documentation - Structure serves as living documentation
7. Scalability - Easy to add new components in right place

Migration Status

• Create folder structure
• Create index files with exports
• Create README documentation
• Move molecules to new folder (optional - can use exports)
• Update import paths throughout codebase
• Update tests
• Verify build

Note: The current implementation uses virtual organization via index.ts exports. Components can physically stay where they are, but are logically organized through the index files. This avoids breaking existing imports while providing clear atomic structure.

Usage Examples

Building a Feature with Atomic Design

// Use atoms for basic elements
import { Button, Input, Label, Badge } from '@/components/atoms'

// Use molecules for simple composites
import { ProfileCard, AppHeader } from '@/components/molecules'

// Use organisms for complex features
import { 
  UserManagement, 
  SchemaEditor 
} from '@/components/organisms'

function MyFeature() {
  return (
    <div>
      <AppHeader />
      <UserManagement />
      <ProfileCard user={currentUser} />
    </div>
  )
}

Creating New Components

New Atom (rare): Only if shadcn doesn't provide it.

// src/components/atoms/CustomIcon.tsx
export function CustomIcon({ name }: CustomIconProps) {
  return <svg>...</svg>
}

New Molecule: Combination of 2-5 atoms.

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

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

New Organism: Complex feature with business logic.

// src/components/organisms/AdvancedSearch.tsx
import { Button, Input } from '@/components/atoms'
import { SearchBar } from '@/components/molecules'
import { useKV } from '@github/spark/hooks'

export function AdvancedSearch() {
  const [history, setHistory] = useKV('search-history', [])
  // Complex search logic...
  return (...)
}

Testing Strategy

Atoms

Test in isolation with simple props:

test('Button renders correctly', () => {
  render(<Button>Click me</Button>)
  expect(screen.getByText('Click me')).toBeInTheDocument()
})

Molecules

Test composition and interaction:

test('ProfileCard displays user info', () => {
  const user = { name: 'John', email: 'john@example.com' }
  render(<ProfileCard user={user} />)
  expect(screen.getByText('John')).toBeInTheDocument()
})

Organisms

Test integration and business logic:

test('UserManagement creates new user', async () => {
  render(<UserManagement />)
  await userEvent.click(screen.getByText('Add User'))
  // ... complex interaction tests
})

Future Considerations

1. Physical Migration: If codebase grows significantly, physically move components to atomic folders
2. Storybook: Add Storybook for visual component documentation
3. Component Library: Extract atoms/molecules to separate package
4. Design System: Formalize design tokens and component variants
5. Auto-generation: Generate component documentation from TypeScript types