mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-05-02 17:55:07 +00:00
Complete organism audit and create comprehensive documentation
Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
@@ -0,0 +1,105 @@
|
||||
# Organism Audit - Key Action Items
|
||||
|
||||
Based on the [Organism Composition Audit](ORGANISM_COMPOSITION_AUDIT.md), here are the prioritized action items:
|
||||
|
||||
## Immediate Actions (Complete)
|
||||
|
||||
- [x] Audit all organism files for composition patterns
|
||||
- [x] Document findings in comprehensive audit report
|
||||
- [x] Update `docs/todo/core/2-TODO.md` to mark audit as complete
|
||||
|
||||
## High Priority (Should address in Q1 2026)
|
||||
|
||||
### 1. Split Oversized Organisms
|
||||
|
||||
**Pagination.tsx (405 LOC)**
|
||||
- Extract `SimplePagination` molecule
|
||||
- Extract `PaginationInfo` molecule
|
||||
- Extract `PerPageSelector` molecule
|
||||
|
||||
**Sidebar.tsx (399/309 LOC - 2 versions)**
|
||||
- Extract `SidebarGroup` molecule
|
||||
- Extract `SidebarMenuItem` molecule
|
||||
- Extract `SidebarHeader` molecule
|
||||
- Consolidate or document difference between two versions
|
||||
|
||||
**Navigation.tsx (370 LOC)**
|
||||
- Extract `NavigationItem` molecule
|
||||
- Extract `NavigationDropdown` molecule
|
||||
- Extract `NavigationBrand` molecule
|
||||
|
||||
**Command.tsx (351/299 LOC - 2 versions)**
|
||||
- Extract `CommandItem` molecule
|
||||
- Extract `CommandGroup` molecule
|
||||
- Extract `CommandEmpty` molecule
|
||||
- Consolidate or document difference between two versions
|
||||
|
||||
## Medium Priority
|
||||
|
||||
### 2. Resolve Duplicate Components
|
||||
|
||||
Five organisms have duplicate implementations:
|
||||
1. Command (52 LOC difference)
|
||||
2. Form (66 LOC difference)
|
||||
3. Sheet (65 LOC difference)
|
||||
4. Sidebar (90 LOC difference)
|
||||
5. Table (14 LOC difference)
|
||||
|
||||
**Action Required:**
|
||||
- Review each pair to determine if both are needed
|
||||
- Document the differences if both versions serve different purposes
|
||||
- Consolidate if possible, or create one as a wrapper around the other
|
||||
|
||||
### 3. Extract Common Molecules
|
||||
|
||||
Create reusable molecules from common patterns:
|
||||
- Form field wrappers (label + input + error)
|
||||
- Navigation items with icons
|
||||
- List items with selection states
|
||||
- Modal/dialog headers and footers
|
||||
- Search bars with filters
|
||||
|
||||
## Low Priority
|
||||
|
||||
### 4. Add Documentation
|
||||
|
||||
Enhance JSDoc comments for organisms:
|
||||
- When to use each organism vs alternatives
|
||||
- Composition patterns and best practices
|
||||
- Code examples for common use cases
|
||||
|
||||
### 5. Establish Size Monitoring
|
||||
|
||||
Add CI/CD checks:
|
||||
- Warn when organism files exceed 150 LOC
|
||||
- Track component complexity metrics
|
||||
- Monitor for circular dependencies
|
||||
|
||||
## Guidelines for Future Organisms
|
||||
|
||||
When creating new organisms:
|
||||
|
||||
1. **Start Small:** Keep initial implementation under 150 LOC
|
||||
2. **Compose First:** Use existing molecules/atoms before creating new ones
|
||||
3. **Single Responsibility:** Each organism should have one clear purpose
|
||||
4. **Extract Early:** If a section grows complex, extract it to a molecule
|
||||
5. **Document:** Add JSDoc with usage examples
|
||||
|
||||
## Success Criteria
|
||||
|
||||
An organism is well-structured when:
|
||||
- ✅ Under 150 LOC (or split into multiple organisms)
|
||||
- ✅ Composes from molecules/atoms (not raw MUI for business logic)
|
||||
- ✅ Has clear single responsibility
|
||||
- ✅ Is documented with JSDoc
|
||||
- ✅ Has focused sub-components as molecules when possible
|
||||
|
||||
## Notes
|
||||
|
||||
- **MUI Direct Imports:** Acceptable for foundational UI organisms that wrap MUI components
|
||||
- **Business Logic Organisms:** Should compose from UI organisms, not MUI directly
|
||||
- **Atomic Design:** Remember the hierarchy: Atoms → Molecules → Organisms → Templates → Pages
|
||||
|
||||
---
|
||||
|
||||
See [ORGANISM_COMPOSITION_AUDIT.md](ORGANISM_COMPOSITION_AUDIT.md) for full details.
|
||||
@@ -0,0 +1,236 @@
|
||||
# Organism Composition Audit Report
|
||||
|
||||
**Date:** 2025-12-27
|
||||
**Auditor:** GitHub Copilot
|
||||
**Scope:** All organism components in MetaBuilder
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This audit reviews all organism components in the MetaBuilder codebase to ensure they follow Atomic Design principles and proper composition patterns. The audit focused on three key areas:
|
||||
|
||||
1. **Import Dependencies** - Ensuring organisms only compose from molecules/atoms
|
||||
2. **File Size** - Identifying oversized organisms (>150 LOC) that need splitting
|
||||
3. **MUI Usage** - Finding opportunities to extract reusable molecules
|
||||
|
||||
### Overall Status: ⚠️ Needs Improvement
|
||||
|
||||
- ✅ **PASS:** No organisms import other organisms (proper isolation)
|
||||
- ⚠️ **REVIEW:** 13 of 14 files exceed 150 LOC threshold
|
||||
- ⚠️ **REVIEW:** All organisms import MUI directly instead of composing from atoms/molecules
|
||||
|
||||
## Inventory
|
||||
|
||||
### Total Organisms: 14 Files
|
||||
|
||||
**Location 1:** `frontends/nextjs/src/components/organisms/`
|
||||
- Command.tsx (299 LOC)
|
||||
- Form.tsx (143 LOC) ✅
|
||||
- NavigationMenu.tsx (251 LOC)
|
||||
- Sheet.tsx (189 LOC)
|
||||
- Sidebar.tsx (399 LOC)
|
||||
- Table.tsx (159 LOC)
|
||||
|
||||
**Location 2:** `frontends/nextjs/src/components/ui/organisms/`
|
||||
- AlertDialog.tsx (268 LOC)
|
||||
- Command.tsx (351 LOC)
|
||||
- Form.tsx (209 LOC)
|
||||
- Navigation.tsx (370 LOC)
|
||||
- Pagination.tsx (405 LOC)
|
||||
- Sheet.tsx (254 LOC)
|
||||
- Sidebar.tsx (309 LOC)
|
||||
- Table.tsx (173 LOC)
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### 1. Import Dependencies ✅ PASS
|
||||
|
||||
**Finding:** No organisms import other organisms.
|
||||
|
||||
**Evidence:**
|
||||
```bash
|
||||
grep -rn "from.*organisms" organisms/ --include="*.tsx"
|
||||
# Result: No matches (excluding README.md)
|
||||
```
|
||||
|
||||
**Conclusion:** Organisms are properly isolated and don't create circular dependencies.
|
||||
|
||||
### 2. File Size Analysis ⚠️ NEEDS ATTENTION
|
||||
|
||||
**Finding:** 13 of 14 organism files exceed the 150 LOC threshold set in TODO.
|
||||
|
||||
| File | LOC | Status | Priority |
|
||||
|------|-----|--------|----------|
|
||||
| Pagination.tsx (UI) | 405 | ❌ | HIGH |
|
||||
| Sidebar.tsx (organisms) | 399 | ❌ | HIGH |
|
||||
| Navigation.tsx (UI) | 370 | ❌ | HIGH |
|
||||
| Command.tsx (UI) | 351 | ❌ | HIGH |
|
||||
| Sidebar.tsx (UI) | 309 | ❌ | MEDIUM |
|
||||
| Command.tsx (organisms) | 299 | ❌ | MEDIUM |
|
||||
| AlertDialog.tsx (UI) | 268 | ❌ | MEDIUM |
|
||||
| Sheet.tsx (UI) | 254 | ❌ | MEDIUM |
|
||||
| NavigationMenu.tsx | 251 | ❌ | MEDIUM |
|
||||
| Form.tsx (UI) | 209 | ❌ | LOW |
|
||||
| Sheet.tsx (organisms) | 189 | ❌ | LOW |
|
||||
| Table.tsx (UI) | 173 | ❌ | LOW |
|
||||
| Table.tsx (organisms) | 159 | ❌ | LOW |
|
||||
| Form.tsx (organisms) | 143 | ✅ | N/A |
|
||||
|
||||
**Recommendation:** Split large organisms into smaller, focused organisms or extract reusable sub-components into molecules.
|
||||
|
||||
### 3. MUI Direct Import Analysis ⚠️ NEEDS REVIEW
|
||||
|
||||
**Finding:** All organisms import MUI components directly instead of composing from atoms/molecules.
|
||||
|
||||
**Current Pattern:**
|
||||
```typescript
|
||||
// Current: Direct MUI imports in organisms
|
||||
import { Box, Button, Typography, Menu, MenuItem } from '@mui/material'
|
||||
```
|
||||
|
||||
**Expected Pattern:**
|
||||
```typescript
|
||||
// Expected: Compose from atoms/molecules
|
||||
import { Button } from '@/components/atoms'
|
||||
import { Card, Dialog } from '@/components/molecules'
|
||||
```
|
||||
|
||||
**Affected Files:**
|
||||
- All 14 organism files import directly from `@mui/material`
|
||||
|
||||
**Rationale for MUI Imports:**
|
||||
Upon inspection, most organisms are foundational UI components that:
|
||||
1. Wrap MUI components with MetaBuilder-specific conventions
|
||||
2. Serve as the building blocks for other organisms
|
||||
3. Are themselves the "molecules" being composed
|
||||
|
||||
**Conclusion:** This is acceptable for foundational UI organisms. However, business logic organisms (when added) should compose from these UI organisms rather than MUI directly.
|
||||
|
||||
### 4. Duplication Analysis
|
||||
|
||||
**Finding:** Several organisms have duplicate implementations in two directories.
|
||||
|
||||
| Component | Location 1 | Location 2 | LOC Diff |
|
||||
|-----------|-----------|-----------|----------|
|
||||
| Command | organisms/ (299) | ui/organisms/ (351) | 52 |
|
||||
| Form | organisms/ (143) | ui/organisms/ (209) | 66 |
|
||||
| Sheet | organisms/ (189) | ui/organisms/ (254) | 65 |
|
||||
| Sidebar | organisms/ (399) | ui/organisms/ (309) | 90 |
|
||||
| Table | organisms/ (159) | ui/organisms/ (173) | 14 |
|
||||
|
||||
**Recommendation:**
|
||||
1. Review if both versions are needed
|
||||
2. If yes, document the difference (e.g., one for UI library, one for app-specific)
|
||||
3. If no, consolidate to single implementation
|
||||
4. Consider if one should be a wrapper around the other
|
||||
|
||||
## Compliance with Atomic Design
|
||||
|
||||
### ✅ What's Working Well
|
||||
|
||||
1. **Clear Separation:** No organism imports other organisms
|
||||
2. **Consistent Structure:** All organisms follow similar patterns
|
||||
3. **MUI Integration:** Proper use of Material-UI components
|
||||
4. **TypeScript:** Full type safety with proper interfaces
|
||||
|
||||
### ⚠️ Areas for Improvement
|
||||
|
||||
1. **File Size:** 13/14 files exceed 150 LOC threshold
|
||||
2. **Component Extraction:** Opportunities to extract molecules:
|
||||
- Navigation items/links
|
||||
- Form field wrappers
|
||||
- Table cell variants
|
||||
- Pagination controls
|
||||
- Command items/groups
|
||||
|
||||
3. **Documentation:** Some organisms lack JSDoc comments explaining:
|
||||
- When to use vs alternatives
|
||||
- Composition patterns
|
||||
- Example usage
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Priority 1: Document Current State (This Audit)
|
||||
- [x] Create this audit report
|
||||
- [ ] Update TODO.md to mark audit as complete
|
||||
- [ ] Share findings with team
|
||||
|
||||
### Priority 2: Address File Size (Medium-term)
|
||||
Split oversized organisms:
|
||||
|
||||
**Pagination.tsx (405 LOC)** → Extract:
|
||||
- `SimplePagination` molecule
|
||||
- `PaginationInfo` molecule
|
||||
- `PerPageSelector` molecule
|
||||
|
||||
**Sidebar.tsx (399/309 LOC)** → Extract:
|
||||
- `SidebarGroup` molecule
|
||||
- `SidebarMenuItem` molecule
|
||||
- `SidebarHeader` molecule
|
||||
|
||||
**Navigation.tsx (370 LOC)** → Extract:
|
||||
- `NavigationItem` molecule
|
||||
- `NavigationDropdown` molecule
|
||||
- `NavigationBrand` molecule
|
||||
|
||||
**Command.tsx (351/299 LOC)** → Extract:
|
||||
- `CommandItem` molecule
|
||||
- `CommandGroup` molecule
|
||||
- `CommandEmpty` molecule
|
||||
|
||||
### Priority 3: Extract Molecules (Long-term)
|
||||
Identify and extract reusable patterns:
|
||||
1. Form field components
|
||||
2. Navigation items
|
||||
3. List items with icons
|
||||
4. Modal/dialog patterns
|
||||
5. Search bars
|
||||
|
||||
### Priority 4: Consolidate Duplicates
|
||||
Review and consolidate duplicate organisms:
|
||||
1. Determine if both versions are needed
|
||||
2. Document differences if both required
|
||||
3. Consolidate if possible
|
||||
4. Create wrapper pattern if appropriate
|
||||
|
||||
## Atomic Design Guidelines Compliance
|
||||
|
||||
| Guideline | Status | Notes |
|
||||
|-----------|--------|-------|
|
||||
| Atoms have no molecule/organism deps | N/A | No atoms in audit scope |
|
||||
| Molecules compose 2-5 atoms | N/A | No molecules in audit scope |
|
||||
| Organisms compose molecules/atoms | ⚠️ | Organisms use MUI directly (acceptable for UI library) |
|
||||
| No circular dependencies | ✅ | Pass - no organism imports organisms |
|
||||
| Files under 150 LOC | ❌ | Fail - 13/14 exceed threshold |
|
||||
| Components are focused | ⚠️ | Some organisms have multiple concerns |
|
||||
|
||||
## Conclusion
|
||||
|
||||
The organism layer is **structurally sound** but needs **refactoring for maintainability**:
|
||||
|
||||
1. ✅ **Dependencies are correct** - no improper imports
|
||||
2. ⚠️ **Size is excessive** - most files need splitting
|
||||
3. ⚠️ **MUI usage is direct** - acceptable for UI foundation layer
|
||||
4. ⚠️ **Some duplication exists** - needs consolidation review
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. ✅ Complete this audit
|
||||
2. Update `docs/todo/core/2-TODO.md` to mark organism audit as complete
|
||||
3. Create follow-up tasks for:
|
||||
- Splitting oversized organisms
|
||||
- Extracting common molecules
|
||||
- Resolving duplicates
|
||||
4. Establish size monitoring in CI/CD
|
||||
|
||||
## References
|
||||
|
||||
- [Atomic Design by Brad Frost](https://atomicdesign.bradfrost.com/)
|
||||
- [TODO 2: Architecture and Refactoring](../todo/core/2-TODO.md)
|
||||
- [Component Architecture README](../../frontends/nextjs/src/components/README.md)
|
||||
- [Organisms README](../../frontends/nextjs/src/components/organisms/README.md)
|
||||
|
||||
---
|
||||
|
||||
**Audit Status:** ✅ Complete
|
||||
**Action Required:** Medium (improvements recommended, not critical)
|
||||
**Follow-up Date:** Q1 2026 (refactoring phase)
|
||||
@@ -19,7 +19,7 @@
|
||||
- [ ] Create missing common molecules (form fields, search bars, nav items)
|
||||
|
||||
### Organisms (`src/components/organisms/`)
|
||||
- [ ] Audit organisms for proper composition of molecules/atoms
|
||||
- [x] Audit organisms for proper composition of molecules/atoms (See: `docs/audits/ORGANISM_COMPOSITION_AUDIT.md`)
|
||||
- [ ] Split oversized organisms (>150 LOC) into smaller organisms
|
||||
- [ ] Document organism data flow and state management
|
||||
- [ ] Ensure organisms handle layout, molecules handle interaction
|
||||
|
||||
Reference in New Issue
Block a user