mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-24 13:54:57 +00:00
chore: cleanup documentation and migrate remaining MUI dependencies
- Remove outdated documentation files from root and docs/ - Clean up generated workflow and audit documentation - Complete fakemui migration in workflowui - Remove remaining SCSS modules - Update package dependencies across all packages - Reorganize documentation structure Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -12,6 +12,7 @@
|
||||
| Document | Location | Purpose |
|
||||
|----------|----------|---------|
|
||||
| **Core Development Guide** | [docs/CLAUDE.md](./docs/CLAUDE.md) | Full development principles, patterns, workflows |
|
||||
| **WorkflowUI Guide** | [CLAUDE.md](./CLAUDE.md) | Frontend dependencies, scope safety, MUI ban |
|
||||
| **CodeForge IDE Guide** | [codegen/CLAUDE.md](./codegen/CLAUDE.md) | JSON-to-React migration, component system |
|
||||
| **Pastebin Conventions** | [pastebin/CLAUDE.md](./pastebin/CLAUDE.md) | Documentation file organization |
|
||||
| **Domain-Specific Rules** | [docs/AGENTS.md](./docs/AGENTS.md) | Task-specific guidance |
|
||||
|
||||
288
docs/DOCS_INDEX.md
Normal file
288
docs/DOCS_INDEX.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# Documentation Index - Organized by Subsystem
|
||||
|
||||
**Last Updated**: 2026-01-23
|
||||
|
||||
This index organizes all documentation in `docs/` by subsystem for easier navigation.
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
docs/
|
||||
├── core/ # Core project docs, contracts, and policies
|
||||
├── dbal/ # Database Abstraction Layer (11 files)
|
||||
├── workflow/ # Workflow Engine & Executor (27 files)
|
||||
├── plugins/ # Workflow Plugins (7 files)
|
||||
├── n8n/ # N8N Migration & Compliance (21 files)
|
||||
├── gameengine/ # Game Engine (7 files)
|
||||
├── packages/ # Feature Packages (56 files)
|
||||
├── ui/ # UI Components & Frontends (15 files)
|
||||
├── analysis/ # Analysis & Status (23 files)
|
||||
├── architecture/ # Architectural Docs (6 files)
|
||||
├── archive/ # Legacy & Archived (37 files)
|
||||
├── guides/ # Implementation Guides
|
||||
├── implementation/ # Implementation Specifics
|
||||
├── phases/ # Phase-specific docs
|
||||
├── plans/ # Strategic Plans
|
||||
├── testing/ # Testing Documentation
|
||||
└── workflow/ # Workflow Examples & Specs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## By Subsystem
|
||||
|
||||
### Core (11 files)
|
||||
Core project documents, policies, and general guidance.
|
||||
|
||||
- **AGENTS.md** - Domain-specific rules and task guidance
|
||||
- **CONTRACT.md** - Development contract and standards
|
||||
- **CLAUDE.md** - Main AI Assistant guide (sync with root)
|
||||
- **CODE_REVIEW_FINDINGS.md** - Code review standards
|
||||
- **PROMPT.md** - System prompts and instructions
|
||||
- **CI_CD_WORKFLOW_INTEGRATION.md** - CI/CD integration details
|
||||
- **IMPLEMENTATION_VERIFICATION.md** - Verification checklist
|
||||
- **EXECUTOR_VALIDATION_ERROR_HANDLING_SUMMARY.md** - Error handling specs
|
||||
- **VARIABLES_ENHANCEMENT_SUMMARY.md** - Variable system enhancements
|
||||
- **WEEK_2_IMPLEMENTATION_ROADMAP.md** - Implementation roadmap
|
||||
- **PHASE3_WEEK4_DELIVERY_SUMMARY.md** - Delivery status
|
||||
- **SMTP_RELAY_INTEGRATION.md** - SMTP integration guide
|
||||
|
||||
### DBAL (11 files)
|
||||
Database Abstraction Layer documentation.
|
||||
|
||||
- **DBAL_ANALYSIS_SUMMARY.md** - Analysis summary
|
||||
- **DBAL_ARCHITECTURE_ANALYSIS.md** - Architecture deep dive
|
||||
- **DBAL_DOCUMENTATION_INDEX.md** - Documentation index
|
||||
- **DBAL_INTEGRATION_GUIDE.md** - Integration guide
|
||||
- **DBAL_QUICK_REFERENCE.md** - Quick reference
|
||||
- **DBAL_WORKFLOW_DOCUMENTATION_INDEX.md** - Workflow integration index
|
||||
- **DBAL_WORKFLOW_EXTENSION_SPECIFICATION.md** - Workflow extensions
|
||||
- **DBAL_WORKFLOW_INTEGRATION_COMPLETE.md** - Integration completion status
|
||||
- **DBAL_WORKFLOW_INTEGRATION_GUIDE.md** - Full integration guide
|
||||
- **DBAL_WORKFLOW_QUICK_REFERENCE.md** - Workflow quick reference
|
||||
- **DBAL_WORKFLOW_SPECIFICATION_SUMMARY.md** - Specification summary
|
||||
|
||||
### Workflow Engine (27 files)
|
||||
Workflow executor, DAG engine, and related documentation.
|
||||
|
||||
- **WORKFLOW_DOCUMENTATION_INDEX.md** - Main documentation index
|
||||
- **WORKFLOW_EXECUTOR_ANALYSIS.md** - Executor analysis
|
||||
- **WORKFLOW_EXECUTOR_INDEX.md** - Executor documentation index
|
||||
- **WORKFLOW_EXECUTOR_INTEGRATION_POINTS.md** - Integration points
|
||||
- **WORKFLOW_EXECUTOR_QUICK_REFERENCE.md** - Quick reference
|
||||
- **WORKFLOW_LOADERV2_IMPLEMENTATION.md** - LoaderV2 implementation
|
||||
- **WORKFLOW_LOADERV2_INTEGRATION_GUIDE.md** - LoaderV2 integration
|
||||
- **WORKFLOW_LOADERV2_INTEGRATION_PLAN.md** - LoaderV2 integration plan
|
||||
- **WORKFLOW_LOADERV2_QUICK_REFERENCE.md** - LoaderV2 quick reference
|
||||
- **WORKFLOW_LOADERV2_SUMMARY.txt** - LoaderV2 summary
|
||||
- **WORKFLOW_ENDPOINTS_REFERENCE.md** - API endpoint reference
|
||||
- **WORKFLOW_COMPLIANCE_README.md** - Compliance guide
|
||||
- **WORKFLOW_COMPLIANCE_FIXER_GUIDE.md** - Fixing compliance issues
|
||||
- **WORKFLOW_COMPLIANCE_IMPLEMENTATION.md** - Compliance implementation
|
||||
- **WORKFLOW_VALIDATION_CHECKLIST.md** - Validation checklist
|
||||
- **WORKFLOW_INVENTORY.md** - Workflow inventory
|
||||
- **WORKFLOW_API_INTEGRATION_UPDATES.md** - API integration updates
|
||||
- **WORKFLOW_SERVICE_ANALYSIS_SUMMARY.md** - Service analysis
|
||||
- **WORKFLOW_UPDATE_SUMMARY.txt** - Update summary
|
||||
- **WORKFLOW_PLUGINS_ARCHITECTURE.md** - Plugin architecture
|
||||
- **WORKFLOW_PLUGINS_COMPLETION_SUMMARY.md** - Plugin completion
|
||||
- **DAG_EXECUTOR_DOCUMENTATION_INDEX.md** - DAG executor index
|
||||
- **DAG_EXECUTOR_N8N_INTEGRATION_ANALYSIS.md** - N8N integration analysis
|
||||
- **DAG_EXECUTOR_QUICK_START.md** - Quick start guide
|
||||
- **DAG_EXECUTOR_TECHNICAL_REFERENCE.md** - Technical reference
|
||||
- **SUBPROJECT_WORKFLOW_UPDATE_GUIDE.md** - Subproject workflow guide
|
||||
|
||||
### Plugins (7 files)
|
||||
Workflow plugin system documentation.
|
||||
|
||||
- **PLUGIN_REGISTRY_START_HERE.md** - Starting point
|
||||
- **PLUGIN_REGISTRY_INDEX.md** - Plugin index
|
||||
- **PLUGIN_REGISTRY_IMPLEMENTATION_PLAN.md** - Implementation plan
|
||||
- **PLUGIN_REGISTRY_CODE_TEMPLATES.md** - Code templates
|
||||
- **PLUGIN_REGISTRY_QUICK_START.md** - Quick start
|
||||
- **PLUGIN_REGISTRY_SUMMARY.md** - Summary
|
||||
- **PLUGIN_INITIALIZATION_GUIDE.md** - Initialization guide
|
||||
|
||||
### N8N Migration (21 files)
|
||||
N8N compliance and migration documentation.
|
||||
|
||||
- **N8N_MIGRATION_STATUS.md** - Migration status
|
||||
- **N8N_INTEGRATION_COMPLETE.md** - Integration completion
|
||||
- **N8N_COMPLIANCE_AUDIT.md** - Compliance audit
|
||||
- **N8N_COMPLIANCE_AUDIT_INDEX.md** - Audit index
|
||||
- **N8N_COMPLIANCE_AUDIT_USER_MANAGER.md** - User manager audit
|
||||
- **N8N_COMPLIANCE_ANALYSIS_2026-01-22.md** - Compliance analysis
|
||||
- **N8N_COMPLIANCE_QUICK_FIX.md** - Quick fix guide
|
||||
- **N8N_COMPLIANCE_FIX_CHECKLIST.md** - Fix checklist
|
||||
- **N8N_VARIABLES_GUIDE.md** - Variables guide
|
||||
- **N8N_SCHEMA_GAPS.md** - Schema gaps analysis
|
||||
- **N8N_PHASE3_WEEK1_COMPLETE.md** - Phase 3 Week 1 status
|
||||
- **N8N_PHASE3_WEEK3_EXECUTIVE_SUMMARY.md** - Phase 3 Week 3 summary
|
||||
- **N8N_PHASE3_WEEKS_1_3_COMPLETE.md** - Phase 3 completion
|
||||
- **N8N_AUDIT_LOG_COMPLIANCE.md** - Audit log compliance
|
||||
- **N8N_GAMEENGINE_COMPLIANCE_AUDIT.md** - GameEngine compliance
|
||||
- **N8N_COMPLIANCE_GAMEENGINE_INDEX.md** - GameEngine compliance index
|
||||
- **N8N_GAMEENGINE_ASSETS_AUDIT.md** - GameEngine assets audit
|
||||
- **N8N_GAMEENGINE_ASSETS_COMPLIANCE_SUMMARY.md** - Assets compliance summary
|
||||
- **N8N_MATERIALX_COMPLIANCE_AUDIT.md** - MaterialX compliance
|
||||
- **N8N_MATERIALX_QUICK_REFERENCE.md** - MaterialX quick reference
|
||||
- **N8N_MATERIALX_COMPLIANCE_SUMMARY.json** - MaterialX compliance summary
|
||||
|
||||
### GameEngine (7 files)
|
||||
Game engine documentation.
|
||||
|
||||
- **GAMEENGINE_PACKAGES_COMPREHENSIVE_AUDIT.md** - Comprehensive audit
|
||||
- **GAMEENGINE_PACKAGES_QUICK_REFERENCE.md** - Quick reference
|
||||
- **GAMEENGINE_GUI_N8N_COMPLIANCE_AUDIT.md** - GUI compliance audit
|
||||
- **GAMEENGINE_SEED_WORKFLOW_N8N_AUDIT.md** - Seed workflow audit
|
||||
- **QUAKE3_WORKFLOW_COMPLIANCE_AUDIT.md** - Quake3 compliance
|
||||
- **SOUNDBOARD_WORKFLOW_COMPLIANCE_AUDIT.md** - Soundboard compliance
|
||||
- **ENGINE_TESTER_N8N_COMPLIANCE_AUDIT.md** - Engine tester compliance
|
||||
|
||||
### Packages (56 files)
|
||||
Documentation for 62 feature packages in the system.
|
||||
|
||||
#### Forum Forge (4 files)
|
||||
- FORUM_FORGE_N8N_COMPLIANCE_REPORT.md
|
||||
- FORUM_FORGE_WORKFLOW_UPDATE_PLAN.md
|
||||
- + 2 files in analysis/
|
||||
|
||||
#### IRC Webchat (5 files)
|
||||
- IRC_WEBCHAT_DOCUMENTATION_INDEX.md
|
||||
- IRC_WEBCHAT_N8N_COMPLIANCE_AUDIT.md
|
||||
- IRC_WEBCHAT_QUICK_REFERENCE.md
|
||||
- IRC_WEBCHAT_SCHEMA_UPDATES.md
|
||||
- IRC_WEBCHAT_WORKFLOW_UPDATE_PLAN.md
|
||||
|
||||
#### Media Center (4 files)
|
||||
- MEDIA_CENTER_DOCUMENTATION_INDEX.md
|
||||
- MEDIA_CENTER_IMPLEMENTATION_CHECKLIST.md
|
||||
- MEDIA_CENTER_SCHEMA_MIGRATION_GUIDE.md
|
||||
- MEDIA_CENTER_WORKFLOW_UPDATE_PLAN.md
|
||||
|
||||
#### Notification Center (3 files)
|
||||
- NOTIFICATION_CENTER_COMPLIANCE_AUDIT.md
|
||||
- NOTIFICATION_CENTER_WORKFLOW_UPDATE_PLAN.md
|
||||
- + 1 file in analysis/
|
||||
|
||||
#### Stream Cast (7 files)
|
||||
- STREAM_CAST_AUDIT_INDEX.md
|
||||
- STREAM_CAST_N8N_COMPLIANCE_AUDIT.md
|
||||
- STREAM_CAST_TECHNICAL_ISSUES.md
|
||||
- STREAM_CAST_WORKFLOW_INDEX.md
|
||||
- STREAM_CAST_WORKFLOW_QUICK_REFERENCE.md
|
||||
- STREAM_CAST_WORKFLOW_README.md
|
||||
- STREAM_CAST_WORKFLOW_TECHNICAL_DETAILS.md
|
||||
- STREAM_CAST_WORKFLOW_UPDATE_PLAN.md
|
||||
|
||||
#### Audit Log (1 file)
|
||||
- AUDIT_LOG_WORKFLOW_UPDATE_PLAN.md
|
||||
|
||||
#### User Manager (4 files)
|
||||
- USER_MANAGER_DELIVERABLES_SUMMARY.md
|
||||
- USER_MANAGER_IMPLEMENTATION_CHECKLIST.md
|
||||
- USER_MANAGER_QUICK_REFERENCE.md
|
||||
- USER_MANAGER_WORKFLOW_UPDATE_PLAN.md
|
||||
|
||||
#### PackageRepo (3 files)
|
||||
- PACKAGEREPO_AUDIT_INDEX.md
|
||||
- PACKAGEREPO_ISSUES_MATRIX.md
|
||||
- PACKAGEREPO_WORKFLOW_COMPLIANCE.md
|
||||
|
||||
#### Dashboard (5 files)
|
||||
- DASHBOARD_WORKFLOW_COMPLIANCE_AUDIT.md
|
||||
- DASHBOARD_WORKFLOW_IMPLEMENTATION.md
|
||||
- DASHBOARD_WORKFLOW_QUICK_REFERENCE.md
|
||||
- DASHBOARD_WORKFLOW_README.md
|
||||
- DASHBOARD_WORKFLOW_UPDATE_PLAN.md
|
||||
|
||||
#### Data Table (5 files)
|
||||
- DATA_TABLE_N8N_COMPLIANCE_AUDIT.md
|
||||
- DATA_TABLE_WORKFLOW_IMPLEMENTATION_GUIDE.md
|
||||
- DATA_TABLE_WORKFLOW_JSON_EXAMPLES.md
|
||||
- DATA_TABLE_WORKFLOW_UPDATE_PLAN.md
|
||||
- DATA_TABLE_WORKFLOW_VALIDATION_CHECKLIST.md
|
||||
|
||||
### UI Components & Frontends (15 files)
|
||||
UI and frontend-related documentation.
|
||||
|
||||
- **UI_AUTH_WORKFLOWS_INDEX.md** - Auth workflows index
|
||||
- **UI_AUTH_WORKFLOW_QUICK_REFERENCE.md** - Auth quick reference
|
||||
- **UI_AUTH_WORKFLOW_UPDATE_PLAN.md** - Auth update plan
|
||||
- **UI_AUTH_VALIDATION_TEMPLATE.md** - Auth validation template
|
||||
- **UI_SCHEMA_EDITOR_WORKFLOWS_INDEX.md** - Schema editor index
|
||||
- **UI_SCHEMA_EDITOR_WORKFLOWS_SUMMARY.md** - Schema editor summary
|
||||
- **UI_SCHEMA_EDITOR_WORKFLOW_CHECKLIST.md** - Schema editor checklist
|
||||
- **UI_SCHEMA_EDITOR_WORKFLOW_UPDATE_PLAN.md** - Schema editor update plan
|
||||
- **UI_JSON_SCRIPT_EDITOR_N8N_COMPLIANCE_AUDIT.md** - JSON script editor audit
|
||||
- **UI_SCHEMA_EDITOR_N8N_COMPLIANCE_REPORT.md** - Schema editor compliance
|
||||
- **UI_WORKFLOW_EDITOR_UPDATE_PLAN.md** - Workflow editor update plan
|
||||
- **UI_DATABASE_MANAGER_WORKFLOWS_QUICK_REFERENCE.md** - Database manager quick ref
|
||||
- **UI_DATABASE_MANAGER_WORKFLOWS_UPDATE_PLAN.md** - Database manager update plan
|
||||
- **NEXTJS_WORKFLOW_SERVICE_MAP.md** - Next.js workflow service map
|
||||
- **FRONTEND_WORKFLOW_SERVICE_IMPLEMENTATION.md** - Frontend workflow service
|
||||
|
||||
### Analysis (23 files)
|
||||
Project status, analysis, and assessments.
|
||||
|
||||
Located in `docs/analysis/` - includes:
|
||||
- System health assessments
|
||||
- Competitive analysis
|
||||
- Migration status reports
|
||||
- Executive summaries
|
||||
- Functional priorities
|
||||
|
||||
### Architecture (6 files)
|
||||
Architectural documentation and system design.
|
||||
|
||||
Located in `docs/architecture/` - includes:
|
||||
- System architecture
|
||||
- Component architecture
|
||||
- Universal platform design
|
||||
- DBAL refactoring plans
|
||||
|
||||
### Archive (37 files)
|
||||
Legacy and archived documentation.
|
||||
|
||||
Located in `docs/archive/` - includes:
|
||||
- Historical implementation summaries
|
||||
- Deprecated approaches
|
||||
- Legacy system documentation
|
||||
- Recovery and consolidation guides
|
||||
|
||||
### Guides, Implementation, Phases, Plans, Testing, Workflow
|
||||
Existing subdirectories with specialized documentation.
|
||||
|
||||
---
|
||||
|
||||
## Quick Links
|
||||
|
||||
**Start Here**: [AGENTS.md](./core/AGENTS.md) - Domain-specific rules
|
||||
|
||||
**For Developers**:
|
||||
- [DBAL Integration](./dbal/DBAL_INTEGRATION_GUIDE.md)
|
||||
- [Workflow Engine](./workflow/WORKFLOW_DOCUMENTATION_INDEX.md)
|
||||
- [Plugin System](./plugins/PLUGIN_REGISTRY_START_HERE.md)
|
||||
|
||||
**For Package Maintainers**:
|
||||
- [Packages Overview](./packages/)
|
||||
- [Package Implementation Guides](./guides/)
|
||||
|
||||
**For Operations**:
|
||||
- [Architecture Overview](./architecture/ARCHITECTURE.md)
|
||||
- [Compliance Documentation](./n8n/)
|
||||
|
||||
**Project Status**:
|
||||
- [Analysis & Status](./analysis/METABUILDER_STATUS_2026-01-21.md)
|
||||
- [Roadmap](./ROADMAP.md)
|
||||
|
||||
---
|
||||
|
||||
## Statistics
|
||||
|
||||
- **Total Files**: ~155 markdown documents
|
||||
- **Subsystems Documented**: 8 major systems
|
||||
- **Organized By**: Subsystem/module
|
||||
- **Last Reorganized**: 2026-01-23
|
||||
368
docs/INDEX_TIER2_ANALYSIS.md
Normal file
368
docs/INDEX_TIER2_ANALYSIS.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# Tier 2 Data Hooks Analysis - Complete Documentation Index
|
||||
|
||||
**Status:** ANALYSIS_COMPLETE
|
||||
**Date:** January 23, 2026
|
||||
**Scope:** Extract and standardize Tier 2 hooks across MetaBuilder frontends
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
**New to this analysis?** Start here:
|
||||
|
||||
1. **30-second summary:** [TIER2_ANALYSIS_SUMMARY.txt](./TIER2_ANALYSIS_SUMMARY.txt)
|
||||
2. **5-minute executive summary:** [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md)
|
||||
3. **Full technical details:** [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md)
|
||||
4. **Implementation guide:** [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md)
|
||||
5. **Quick reference:** [TIER2_HOOKS_REFERENCE.md](./TIER2_HOOKS_REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
## Document Guide
|
||||
|
||||
### 1. TIER2_ANALYSIS_SUMMARY.txt (9.2 KB)
|
||||
**For:** Anyone wanting a quick overview
|
||||
**Contains:**
|
||||
- All key statistics and findings
|
||||
- Fragmentation issues (4 problems)
|
||||
- Proposed solution summary
|
||||
- Implementation timeline
|
||||
- Success metrics
|
||||
- Next steps checklist
|
||||
|
||||
**Read this if:** You need to understand the problem and solution in 5 minutes
|
||||
|
||||
---
|
||||
|
||||
### 2. TIER2_EXTRACTION_STRATEGY.md (10 KB)
|
||||
**For:** Decision makers and architects
|
||||
**Contains:**
|
||||
- Key findings (11 hooks found)
|
||||
- Common patterns (5 identified)
|
||||
- Fragmentation issues breakdown
|
||||
- Proposed adapter pattern
|
||||
- Implementation timeline with phases
|
||||
- Benefits and risk mitigation
|
||||
- Immediate next steps
|
||||
|
||||
**Read this if:** You need to decide on architecture and timeline
|
||||
|
||||
---
|
||||
|
||||
### 3. TIER2_HOOKS_ANALYSIS.md (24 KB, 772 lines)
|
||||
**For:** Technical leads implementing the solution
|
||||
**Contains:**
|
||||
- Complete Tier 2 hooks inventory by frontend
|
||||
- Redux infrastructure analysis (slices, selectors, actions)
|
||||
- Service layer architecture
|
||||
- Common implementation patterns (pagination, search, error handling, caching, tenancy)
|
||||
- Proposed adapter pattern in detail
|
||||
- Standardized features to extract
|
||||
- Migration path (Phase 5 steps)
|
||||
- Benefits, risks, and success metrics
|
||||
- Comparison matrix of current implementations
|
||||
|
||||
**Read this if:** You're implementing Phase 5 or need deep technical understanding
|
||||
|
||||
---
|
||||
|
||||
### 4. TIER2_ADAPTER_ARCHITECTURE.md (27 KB, 1,032 lines)
|
||||
**For:** Developers implementing the adapters
|
||||
**Contains:**
|
||||
- Full architecture diagrams (ASCII and descriptions)
|
||||
- BaseServiceAdapter interface specification
|
||||
- ReduxAdapter implementation (with code examples)
|
||||
- APIAdapter implementation (with code examples)
|
||||
- DBALAdapter implementation (with code examples)
|
||||
- Generic useEntity hook factory (full implementation)
|
||||
- Cache layer design
|
||||
- Implementation roadmap with steps
|
||||
- File structure for new packages/tier2-hooks package
|
||||
|
||||
**Read this if:** You're writing the actual adapter and hook code
|
||||
|
||||
---
|
||||
|
||||
### 5. TIER2_HOOKS_REFERENCE.md (11 KB)
|
||||
**For:** Developers using the hooks
|
||||
**Contains:**
|
||||
- Hooks inventory table (all 11 hooks)
|
||||
- Common patterns table (5 patterns)
|
||||
- Unified hook signature (Phase 5 target)
|
||||
- Pattern comparison matrix (features by frontend)
|
||||
- Key implementation details (pagination, search, error handling, caching, tenancy)
|
||||
- Redux integration patterns
|
||||
- API endpoints structure
|
||||
- Service architecture overview
|
||||
- Quick links to all related documentation
|
||||
|
||||
**Read this if:** You're learning how to use the new unified hooks
|
||||
|
||||
---
|
||||
|
||||
## Key Findings Summary
|
||||
|
||||
### Hooks Identified (11 Total)
|
||||
|
||||
**workflowui (4 hooks - Redux + Service):**
|
||||
- `useProject` - Project CRUD + selection
|
||||
- `useWorkspace` - Workspace CRUD + selection
|
||||
- `useWorkflow` - Workflow operations + auto-save
|
||||
- `useExecution` - Execution + history + stats
|
||||
|
||||
**frontends/nextjs (7 hooks - No Redux):**
|
||||
- `useUsers` - List with pagination, search, filtering
|
||||
- `useUserForm` - Form state management
|
||||
- `useUserActions` - User CRUD wrapper
|
||||
- `usePackages` - List with pagination, search
|
||||
- `usePackageDetails` - Single entity + related data
|
||||
- `usePackageActions` - Package CRUD wrapper
|
||||
- `useWorkflow` - Execution with retry + polling
|
||||
|
||||
**Generic Adapters (3):**
|
||||
- `useRestApi` - Generic CRUD builder
|
||||
- `useEntity` - Entity-specific wrapper
|
||||
- `useDependencyEntity` - Cross-package access
|
||||
|
||||
### Patterns Identified (5)
|
||||
|
||||
1. **Basic CRUD + Selection** (useProject, useWorkspace)
|
||||
2. **List + Pagination + Search + Filter** (useUsers, usePackages)
|
||||
3. **Async Action + History + Stats** (useExecution, useWorkflow)
|
||||
4. **Form Management + Actions** (useUserForm, usePackageActions)
|
||||
5. **Single Entity + Related Collections** (usePackageDetails)
|
||||
|
||||
### Fragmentation Issues (4)
|
||||
|
||||
1. **API Schema Differences** - limit/offset vs page/limit vs skip/take
|
||||
2. **State Management Mismatch** - Redux vs useState vs DBAL
|
||||
3. **Feature Gaps** - Search/filter, caching, real-time sync not available everywhere
|
||||
4. **Code Duplication** - ~40% duplicate code across hooks
|
||||
|
||||
### Proposed Solution
|
||||
|
||||
**Service Adapter Pattern** - 3-layer architecture:
|
||||
- Hooks layer (unified API)
|
||||
- Adapter layer (Redux, API, DBAL variants)
|
||||
- Service layer (generic CRUD + retry)
|
||||
- Storage layer (cache + HTTP)
|
||||
|
||||
**Benefits:**
|
||||
- 30-40% code reduction
|
||||
- 100% feature parity
|
||||
- Single implementation
|
||||
- Standardized patterns
|
||||
|
||||
---
|
||||
|
||||
## Implementation Timeline
|
||||
|
||||
**Phase 5: 6-9 weeks (1.5-2 months)**
|
||||
|
||||
- **Phase 5a (1-2 weeks):** Foundation - Adapters, cache, tests
|
||||
- **Phase 5b (2-3 weeks):** Core hooks - useEntity factory, entity hooks
|
||||
- **Phase 5c (2-3 weeks):** Migration - Refactor existing hooks
|
||||
- **Phase 5d (1 week):** Polish - Performance, docs, training
|
||||
|
||||
---
|
||||
|
||||
## New Package Structure
|
||||
|
||||
```
|
||||
packages/tier2-hooks/
|
||||
├── src/
|
||||
│ ├── adapters/ (base, redux, api, dbal)
|
||||
│ ├── cache/ (indexeddb, memory)
|
||||
│ ├── hooks/ (use-entity, use-projects, etc.)
|
||||
│ ├── types/ (interfaces)
|
||||
│ └── utils/ (retry, query-builder)
|
||||
├── tests/ (comprehensive suite)
|
||||
├── docs/ (architecture, migration)
|
||||
└── package.json
|
||||
```
|
||||
|
||||
**Files to refactor:**
|
||||
- workflowui/src/hooks/*.ts
|
||||
- frontends/nextjs/src/hooks/use*.ts
|
||||
|
||||
---
|
||||
|
||||
## Reading Guide by Role
|
||||
|
||||
### Product Manager
|
||||
Read in this order:
|
||||
1. [TIER2_ANALYSIS_SUMMARY.txt](./TIER2_ANALYSIS_SUMMARY.txt) (2 min)
|
||||
2. [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md) (5 min)
|
||||
|
||||
**Why:** Understand the problem, solution, and timeline
|
||||
|
||||
---
|
||||
|
||||
### Architect/Tech Lead
|
||||
Read in this order:
|
||||
1. [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md) (5 min)
|
||||
2. [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) (20 min)
|
||||
3. [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) - Section 1 (10 min)
|
||||
|
||||
**Why:** Design decisions, technical details, implementation planning
|
||||
|
||||
---
|
||||
|
||||
### Backend Developer (Implementing Adapters)
|
||||
Read in this order:
|
||||
1. [TIER2_HOOKS_REFERENCE.md](./TIER2_HOOKS_REFERENCE.md) - Quick ref section (5 min)
|
||||
2. [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) (30 min)
|
||||
3. [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Common patterns (15 min)
|
||||
|
||||
**Why:** Understand the adapter interfaces, implementation examples, and patterns
|
||||
|
||||
---
|
||||
|
||||
### Frontend Developer (Using the Hooks)
|
||||
Read in this order:
|
||||
1. [TIER2_HOOKS_REFERENCE.md](./TIER2_HOOKS_REFERENCE.md) (10 min)
|
||||
2. [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) - Hook factory section (15 min)
|
||||
|
||||
**Why:** Learn the unified hook API and usage patterns
|
||||
|
||||
---
|
||||
|
||||
### Code Reviewer
|
||||
Read in this order:
|
||||
1. [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md) (5 min)
|
||||
2. [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) (25 min)
|
||||
3. [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Common patterns (10 min)
|
||||
|
||||
**Why:** Understand the design, check implementation against spec
|
||||
|
||||
---
|
||||
|
||||
## Navigation by Topic
|
||||
|
||||
### Understanding the Problem
|
||||
- Problem statement: [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md) - Fragmentation Issues section
|
||||
- Detailed analysis: [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Sections II-V
|
||||
- Visual summary: [TIER2_ANALYSIS_SUMMARY.txt](./TIER2_ANALYSIS_SUMMARY.txt) - Fragmentation Issues
|
||||
|
||||
### Understanding the Solution
|
||||
- High-level overview: [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md) - Proposed Solution section
|
||||
- Architecture diagrams: [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) - Architecture Overview section
|
||||
- Detailed design: [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Section VI
|
||||
|
||||
### Implementation Details
|
||||
- Adapter interfaces: [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) - Sections 1-4
|
||||
- Hook factory: [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) - Generic Hook Factory section
|
||||
- Code examples: [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) - Full implementations
|
||||
|
||||
### Timeline & Planning
|
||||
- Summary: [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md) - Migration Strategy section
|
||||
- Detailed phases: [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Section VIII
|
||||
- Roadmap: [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) - Implementation Roadmap section
|
||||
|
||||
### Current Implementations
|
||||
- Workflowui hooks: [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Section I.A
|
||||
- Frontends/nextjs hooks: [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Section I.B
|
||||
- Redux infrastructure: [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Section III
|
||||
- Services: [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Section IV
|
||||
|
||||
### Common Patterns
|
||||
- Overview table: [TIER2_HOOKS_REFERENCE.md](./TIER2_HOOKS_REFERENCE.md) - Common Patterns section
|
||||
- Detailed analysis: [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Section II
|
||||
|
||||
---
|
||||
|
||||
## Questions & Answers
|
||||
|
||||
**Q: Where do I find the list of all 11 hooks?**
|
||||
A: [TIER2_HOOKS_REFERENCE.md](./TIER2_HOOKS_REFERENCE.md) - Hooks Inventory section
|
||||
|
||||
**Q: What are the 5 common patterns?**
|
||||
A: [TIER2_HOOKS_REFERENCE.md](./TIER2_HOOKS_REFERENCE.md) - Common Patterns section or [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md) - Section II
|
||||
|
||||
**Q: How long will Phase 5 take?**
|
||||
A: [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md) - Implementation Timeline section (6-9 weeks total)
|
||||
|
||||
**Q: What files need to be created?**
|
||||
A: [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) - Files Structure section
|
||||
|
||||
**Q: What's the unified hook signature?**
|
||||
A: [TIER2_HOOKS_REFERENCE.md](./TIER2_HOOKS_REFERENCE.md) - Unified Hook Signature section
|
||||
|
||||
**Q: How do the adapters work?**
|
||||
A: [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md) - Adapter Pattern Detailed section
|
||||
|
||||
**Q: What are the risks?**
|
||||
A: [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md) - Risk Assessment section
|
||||
|
||||
**Q: What's the benefit?**
|
||||
A: [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md) - Benefits section
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
### MetaBuilder Architecture
|
||||
- Main guide: [docs/CLAUDE.md](./CLAUDE.md)
|
||||
- Agents guide: [docs/AGENTS.md](./AGENTS.md)
|
||||
- Schemas: [docs/SCHEMAS_COMPREHENSIVE.md](./SCHEMAS_COMPREHENSIVE.md)
|
||||
- Packages: [docs/PACKAGES_INVENTORY.md](./PACKAGES_INVENTORY.md)
|
||||
|
||||
### Source Code References
|
||||
- Redux slices: `/Users/rmac/Documents/metabuilder/redux/slices/src/slices/`
|
||||
- Services: `/Users/rmac/Documents/metabuilder/workflowui/src/services/`
|
||||
- Hooks: `/Users/rmac/Documents/metabuilder/workflowui/src/hooks/`
|
||||
- Frontend hooks: `/Users/rmac/Documents/metabuilder/frontends/nextjs/src/hooks/`
|
||||
|
||||
---
|
||||
|
||||
## Document Statistics
|
||||
|
||||
| Document | Size | Lines | Topics |
|
||||
|----------|------|-------|--------|
|
||||
| TIER2_ANALYSIS_SUMMARY.txt | 9.2 KB | 254 | Overview, findings, timeline |
|
||||
| TIER2_EXTRACTION_STRATEGY.md | 10 KB | 349 | Executive summary, strategy |
|
||||
| TIER2_HOOKS_REFERENCE.md | 11 KB | 410 | Quick reference, tables |
|
||||
| TIER2_HOOKS_ANALYSIS.md | 24 KB | 772 | Complete technical analysis |
|
||||
| TIER2_ADAPTER_ARCHITECTURE.md | 27 KB | 1,032 | Implementation guide, code |
|
||||
| **Total** | **81 KB** | **2,817** | Complete Tier 2 specification |
|
||||
|
||||
---
|
||||
|
||||
## Checklist for Implementation
|
||||
|
||||
Before starting Phase 5:
|
||||
|
||||
- [ ] All stakeholders have reviewed TIER2_EXTRACTION_STRATEGY.md
|
||||
- [ ] Architecture has been approved by tech leads
|
||||
- [ ] Team has read TIER2_ADAPTER_ARCHITECTURE.md
|
||||
- [ ] Phase 5 RFC document has been created
|
||||
- [ ] Sprint planning includes Phase 5a tasks
|
||||
- [ ] Development environment is set up for packages/tier2-hooks
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Distribute these documents** to all stakeholders
|
||||
2. **Schedule architecture review** meeting
|
||||
3. **Create Phase 5 RFC** based on TIER2_EXTRACTION_STRATEGY.md
|
||||
4. **Begin Phase 5a planning** once approved
|
||||
5. **Set up packages/tier2-hooks** repository structure
|
||||
6. **Assign implementation teams** for adapters and hooks
|
||||
|
||||
---
|
||||
|
||||
## Contact & Support
|
||||
|
||||
For questions about this analysis:
|
||||
- Full technical details: [TIER2_HOOKS_ANALYSIS.md](./TIER2_HOOKS_ANALYSIS.md)
|
||||
- Implementation questions: [TIER2_ADAPTER_ARCHITECTURE.md](./TIER2_ADAPTER_ARCHITECTURE.md)
|
||||
- Quick reference: [TIER2_HOOKS_REFERENCE.md](./TIER2_HOOKS_REFERENCE.md)
|
||||
- Strategic questions: [TIER2_EXTRACTION_STRATEGY.md](./TIER2_EXTRACTION_STRATEGY.md)
|
||||
|
||||
---
|
||||
|
||||
**Analysis Complete: January 23, 2026**
|
||||
**Status: ANALYSIS_COMPLETE**
|
||||
**Ready for Phase 5 Planning**
|
||||
|
||||
1032
docs/TIER2_ADAPTER_ARCHITECTURE.md
Normal file
1032
docs/TIER2_ADAPTER_ARCHITECTURE.md
Normal file
File diff suppressed because it is too large
Load Diff
254
docs/TIER2_ANALYSIS_SUMMARY.txt
Normal file
254
docs/TIER2_ANALYSIS_SUMMARY.txt
Normal file
@@ -0,0 +1,254 @@
|
||||
================================================================================
|
||||
TIER 2 DATA HOOKS ANALYSIS - COMPLETE
|
||||
================================================================================
|
||||
|
||||
Date: January 23, 2026
|
||||
Status: ANALYSIS_COMPLETE
|
||||
Scope: Extract and standardize Tier 2 hooks across MetaBuilder frontends
|
||||
|
||||
================================================================================
|
||||
KEY FINDINGS
|
||||
================================================================================
|
||||
|
||||
TIER 2 HOOKS FOUND: 11 Total
|
||||
|
||||
workflowui (4 hooks - Redux + Service + IndexedDB):
|
||||
1. useProject - Project CRUD + selection
|
||||
2. useWorkspace - Workspace CRUD + selection
|
||||
3. useWorkflow - Workflow operations + auto-save
|
||||
4. useExecution - Execution + history + stats
|
||||
|
||||
frontends/nextjs (7 hooks - No Redux):
|
||||
5. useUsers - User list with pagination, search, filtering
|
||||
6. useUserForm - User form state management
|
||||
7. useUserActions - User CRUD operations
|
||||
8. usePackages - Package list with pagination, search
|
||||
9. usePackageDetails - Single package + related data
|
||||
10. usePackageActions - Package CRUD operations
|
||||
11. useWorkflow - Workflow execution + retry logic
|
||||
|
||||
Generic Service Adapters (3 - Available to all):
|
||||
- useRestApi - Generic CRUD builder
|
||||
- useEntity - Entity-specific wrapper
|
||||
- useDependencyEntity - Cross-package access
|
||||
|
||||
================================================================================
|
||||
COMMON PATTERNS IDENTIFIED (5)
|
||||
================================================================================
|
||||
|
||||
Pattern 1: Basic CRUD + Selection
|
||||
Examples: useProject, useWorkspace
|
||||
Components: items[], current, CRUD actions, persistence
|
||||
|
||||
Pattern 2: List with Pagination, Search, Filtering
|
||||
Examples: useUsers, usePackages
|
||||
Components: pagination, debounced search, filtering, refetch
|
||||
|
||||
Pattern 3: Entity Operations + Async Actions
|
||||
Examples: useExecution, useWorkflow(nextjs)
|
||||
Components: status tracking, retry logic, progress metrics
|
||||
|
||||
Pattern 4: Form Management with Actions
|
||||
Examples: useUserForm, usePackageActions
|
||||
Components: field state, validation, submission handling
|
||||
|
||||
Pattern 5: Single Entity + Related Data
|
||||
Examples: usePackageDetails, useProjectCanvas
|
||||
Components: main entity, collections, lazy loading
|
||||
|
||||
================================================================================
|
||||
FRAGMENTATION ISSUES (4 Problems)
|
||||
================================================================================
|
||||
|
||||
Problem 1: API Schema Differences
|
||||
- workflowui: limit, offset, params
|
||||
- frontends/nextjs: page, limit (0-indexed)
|
||||
- useRestApi: skip, take
|
||||
|
||||
Problem 2: State Management Mismatch
|
||||
- workflowui: Redux + service + IndexedDB
|
||||
- frontends/nextjs: useState + direct fetch + AbortController
|
||||
- No unified interface
|
||||
|
||||
Problem 3: Feature Gaps
|
||||
- workflowui: No search/filter support
|
||||
- frontends/nextjs: No caching strategy
|
||||
- No real-time sync adapters
|
||||
|
||||
Problem 4: Code Duplication
|
||||
- Search debouncing implemented separately
|
||||
- Pagination logic repeated
|
||||
- Error handling patterns inconsistent
|
||||
- Retry logic only in workflowui
|
||||
|
||||
================================================================================
|
||||
PROPOSED SOLUTION: SERVICE ADAPTER PATTERN
|
||||
================================================================================
|
||||
|
||||
Architecture: 3-Layer (Hooks → Adapters → Services → Storage)
|
||||
|
||||
Adapters:
|
||||
1. Redux Adapter (workflowui) - dispatch/useSelector + Redux + IndexedDB
|
||||
2. API Adapter (frontends/nextjs) - Direct fetch + useState + Memory cache
|
||||
3. DBAL Adapter (frontends/dbal) - Minimal implementation
|
||||
|
||||
Unified Interface:
|
||||
- All hooks have same signature: useEntity<T>(entityType, options)
|
||||
- All return: UseEntityReturn<T> with identical API
|
||||
- Consistent CRUD, pagination, search, error handling
|
||||
|
||||
Benefits:
|
||||
- 30-40% code reduction
|
||||
- Single implementation for 11+ hooks
|
||||
- 100% feature parity across frontends
|
||||
- Standardized error handling and retry logic
|
||||
- Optional caching (IndexedDB, memory, HTTP)
|
||||
|
||||
================================================================================
|
||||
IMPLEMENTATION TIMELINE: Phase 5 (6-9 weeks)
|
||||
================================================================================
|
||||
|
||||
Phase 5a: Foundation (1-2 weeks)
|
||||
- Create base adapter layer
|
||||
- Implement 3 adapter variants (Redux, API, DBAL)
|
||||
- Create cache layer (IndexedDB, memory)
|
||||
- Write tests
|
||||
|
||||
Phase 5b: Core Hooks (2-3 weeks)
|
||||
- Implement generic useEntity hook
|
||||
- Create entity-specific hooks
|
||||
- Write tests and documentation
|
||||
|
||||
Phase 5c: Migration (2-3 weeks)
|
||||
- Refactor workflowui hooks
|
||||
- Refactor frontends/nextjs hooks
|
||||
- Add dbal support
|
||||
- Integration testing
|
||||
|
||||
Phase 5d: Polish (1 week)
|
||||
- Performance optimization
|
||||
- Error handling improvements
|
||||
- Final documentation
|
||||
|
||||
Total: 6-9 weeks (1.5-2 months)
|
||||
|
||||
================================================================================
|
||||
NEW PACKAGE STRUCTURE
|
||||
================================================================================
|
||||
|
||||
packages/tier2-hooks/
|
||||
├── src/
|
||||
│ ├── adapters/ (base, redux, api, dbal)
|
||||
│ ├── cache/ (indexeddb, memory)
|
||||
│ ├── hooks/ (use-entity, use-projects, use-users, etc.)
|
||||
│ ├── types/ (interfaces)
|
||||
│ └── utils/ (retry, query-builder)
|
||||
├── tests/ (comprehensive test suite)
|
||||
├── docs/ (architecture, migration guide)
|
||||
└── package.json
|
||||
|
||||
Files to Refactor (Phase 5c+):
|
||||
- workflowui/src/hooks/useProject.ts
|
||||
- workflowui/src/hooks/useWorkspace.ts
|
||||
- workflowui/src/hooks/useWorkflow.ts
|
||||
- workflowui/src/hooks/useExecution.ts
|
||||
- frontends/nextjs/src/hooks/useUsers.ts
|
||||
- frontends/nextjs/src/hooks/usePackages.ts
|
||||
- frontends/nextjs/src/hooks/useWorkflow.ts
|
||||
|
||||
================================================================================
|
||||
DELIVERABLE DOCUMENTS
|
||||
================================================================================
|
||||
|
||||
1. TIER2_HOOKS_ANALYSIS.md (Comprehensive - Full Technical Details)
|
||||
Location: /Users/rmac/Documents/metabuilder/docs/TIER2_HOOKS_ANALYSIS.md
|
||||
Contents: Complete analysis, patterns, Redux infrastructure, services, common details
|
||||
|
||||
2. TIER2_EXTRACTION_STRATEGY.md (Executive Summary)
|
||||
Location: /Users/rmac/Documents/metabuilder/docs/TIER2_EXTRACTION_STRATEGY.md
|
||||
Contents: Key findings, fragmentation, solution, timeline, benefits
|
||||
|
||||
3. TIER2_HOOKS_REFERENCE.md (Quick Reference)
|
||||
Location: /Users/rmac/Documents/metabuilder/docs/TIER2_HOOKS_REFERENCE.md
|
||||
Contents: Hook inventory, patterns table, unified signature, quick links
|
||||
|
||||
4. TIER2_ADAPTER_ARCHITECTURE.md (Implementation Guide)
|
||||
Location: /Users/rmac/Documents/metabuilder/docs/TIER2_ADAPTER_ARCHITECTURE.md
|
||||
Contents: Architecture diagrams, adapter code examples, implementation roadmap
|
||||
|
||||
5. TIER2_ANALYSIS_SUMMARY.txt (This File)
|
||||
Location: /Users/rmac/Documents/metabuilder/docs/TIER2_ANALYSIS_SUMMARY.txt
|
||||
Contents: Quick summary, key stats, next steps
|
||||
|
||||
================================================================================
|
||||
NEXT STEPS
|
||||
================================================================================
|
||||
|
||||
1. ✅ [DONE] Analyze existing Tier 2 hooks across codebase
|
||||
2. ✅ [DONE] Document patterns and fragmentation
|
||||
3. ✅ [DONE] Design unified adapter pattern
|
||||
4. [TODO] Present findings to architecture review board
|
||||
5. [TODO] Get approval on adapter design
|
||||
6. [TODO] Create Phase 5 RFC document
|
||||
7. [TODO] Begin Phase 5a: Foundation work
|
||||
|
||||
================================================================================
|
||||
SUCCESS METRICS
|
||||
================================================================================
|
||||
|
||||
Code Quality:
|
||||
- 30-40% reduction in Tier 2 hook lines
|
||||
- 100% of entity CRUD operations covered
|
||||
|
||||
Testing:
|
||||
- >80% test coverage on adapters
|
||||
- >80% test coverage on hooks
|
||||
|
||||
Type Safety:
|
||||
- Zero `any` types in new code
|
||||
- Full TypeScript integration
|
||||
|
||||
Performance:
|
||||
- <5% API response time regression
|
||||
- Improved caching strategy
|
||||
|
||||
Documentation:
|
||||
- 100% of hooks documented with examples
|
||||
- Migration guide for all frontends
|
||||
|
||||
Adoption:
|
||||
- All frontends migrated by end of Phase 5
|
||||
- Zero breaking changes for consumers
|
||||
|
||||
================================================================================
|
||||
RISK MITIGATION
|
||||
================================================================================
|
||||
|
||||
Risk: Redux hooks break during refactor
|
||||
Mitigation: Gradual migration, run both old+new hooks during transition
|
||||
|
||||
Risk: API schema mismatches
|
||||
Mitigation: Adapter layer normalizes differences
|
||||
|
||||
Risk: Cache invalidation bugs
|
||||
Mitigation: Comprehensive test suite + manual invalidation API
|
||||
|
||||
Risk: Performance regression
|
||||
Mitigation: Benchmarking before/after, optimization focus
|
||||
|
||||
Risk: Developer confusion
|
||||
Mitigation: Migration guide + examples + documentation
|
||||
|
||||
================================================================================
|
||||
CONTACT & QUESTIONS
|
||||
================================================================================
|
||||
|
||||
For questions about this analysis, refer to:
|
||||
- Full technical details: TIER2_HOOKS_ANALYSIS.md
|
||||
- Quick reference: TIER2_HOOKS_REFERENCE.md
|
||||
- Implementation details: TIER2_ADAPTER_ARCHITECTURE.md
|
||||
- Strategy & timeline: TIER2_EXTRACTION_STRATEGY.md
|
||||
|
||||
All documents are in: /Users/rmac/Documents/metabuilder/docs/
|
||||
|
||||
================================================================================
|
||||
349
docs/TIER2_EXTRACTION_STRATEGY.md
Normal file
349
docs/TIER2_EXTRACTION_STRATEGY.md
Normal file
@@ -0,0 +1,349 @@
|
||||
# Tier 2 Hooks Extraction Strategy - Executive Summary
|
||||
|
||||
**Status:** ANALYSIS_COMPLETE
|
||||
**Date:** January 23, 2026
|
||||
|
||||
---
|
||||
|
||||
## Key Findings
|
||||
|
||||
### Tier 2 Hooks Found: 11 Total
|
||||
|
||||
**workflowui (4 hooks - Redux-backed):**
|
||||
1. `useProject` - Project CRUD + selection
|
||||
2. `useWorkspace` - Workspace CRUD + selection
|
||||
3. `useWorkflow` - Workflow operations + auto-save
|
||||
4. `useExecution` - Execution + history + stats
|
||||
|
||||
**frontends/nextjs (7 hooks - No Redux):**
|
||||
5. `useUsers` - User list with pagination, search, filtering
|
||||
6. `useUserForm` - User form state management
|
||||
7. `useUserActions` - User CRUD operations
|
||||
8. `usePackages` - Package list with pagination, search
|
||||
9. `usePackageDetails` - Single package + related data
|
||||
10. `usePackageActions` - Package CRUD operations
|
||||
11. `useWorkflow` - Workflow execution + retry logic
|
||||
|
||||
**Generic Service Adapters (3 - Available to all):**
|
||||
- `useRestApi` - Generic CRUD builder (frontends/nextjs)
|
||||
- `useEntity` - Entity-specific wrapper (frontends/nextjs)
|
||||
- `useDependencyEntity` - Cross-package access (frontends/nextjs)
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns (5 Identified)
|
||||
|
||||
| Pattern | Examples | Key Features |
|
||||
|---------|----------|--------------|
|
||||
| **Basic CRUD + Selection** | useProject, useWorkspace | items[], current, CRUD actions, persistence |
|
||||
| **List + Pagination + Search** | useUsers, usePackages | pagination, debounced search, filtering, refetch |
|
||||
| **Async Actions + History** | useExecution, useWorkflow | status tracking, retry logic, progress metrics |
|
||||
| **Form Management** | useUserForm, usePackageActions | field state, validation, submission handling |
|
||||
| **Entity + Related Data** | usePackageDetails | main entity, collections, lazy loading |
|
||||
|
||||
---
|
||||
|
||||
## Fragmentation Issues
|
||||
|
||||
### Problem 1: API Schema Differences
|
||||
- workflowui: `limit`, `offset`, `params`
|
||||
- frontends/nextjs: `page`, `limit` (0-indexed)
|
||||
- useRestApi: `take`, `skip`
|
||||
|
||||
### Problem 2: State Management Mismatch
|
||||
- workflowui: Redux + service + IndexedDB
|
||||
- frontends/nextjs: useState + direct fetch + AbortController
|
||||
- No unified interface
|
||||
|
||||
### Problem 3: Feature Gaps
|
||||
- workflowui: No search/filter support
|
||||
- frontends/nextjs: No caching strategy
|
||||
- No real-time sync adapters anywhere
|
||||
|
||||
### Problem 4: Duplication
|
||||
- Search debouncing implemented separately in each hook
|
||||
- Pagination logic repeated
|
||||
- Error handling patterns inconsistent
|
||||
- Retry logic only in workflowui
|
||||
|
||||
---
|
||||
|
||||
## Proposed Service Adapter Pattern
|
||||
|
||||
### Three-Layer Architecture
|
||||
|
||||
```
|
||||
Tier 2 Hooks (Unified API)
|
||||
↓
|
||||
Adapters (Redux | API | DBAL)
|
||||
↓
|
||||
Service Layer (CRUD + Retry + Query)
|
||||
↓
|
||||
Storage (Cache | Fetch | DBAL)
|
||||
```
|
||||
|
||||
### Unified Hook Interface
|
||||
|
||||
```typescript
|
||||
interface UseEntityReturn<T> {
|
||||
// State
|
||||
items: T[]
|
||||
currentItem: T | null
|
||||
isLoading: boolean
|
||||
error: string | null
|
||||
pagination?: { page, limit, total, totalPages }
|
||||
|
||||
// CRUD Actions
|
||||
list(options?: FetchOptions): Promise<T[]>
|
||||
get(id: string): Promise<T | null>
|
||||
create(data: Partial<T>): Promise<T>
|
||||
update(id: string, data: Partial<T>): Promise<T>
|
||||
delete(id: string): Promise<void>
|
||||
|
||||
// Convenience
|
||||
setCurrent(id: string | null): void
|
||||
refetch(): Promise<void>
|
||||
search?(term: string): Promise<void>
|
||||
filter?(criteria: Record<string, any>): Promise<void>
|
||||
}
|
||||
```
|
||||
|
||||
### Adapter Variants
|
||||
|
||||
**Redux Adapter (workflowui)**
|
||||
- Uses dispatch/useSelector
|
||||
- Maintains Redux state
|
||||
- IndexedDB caching
|
||||
- localStorage persistence
|
||||
|
||||
**API Adapter (frontends/nextjs)**
|
||||
- Direct fetch() calls
|
||||
- useState for local state
|
||||
- AbortController for cancellation
|
||||
- Memory caching optional
|
||||
|
||||
**DBAL Adapter (frontends/dbal)**
|
||||
- Minimal implementation
|
||||
- No caching
|
||||
- No Redux
|
||||
- Stateless
|
||||
|
||||
---
|
||||
|
||||
## Standardized Features to Extract
|
||||
|
||||
### 1. Pagination (Normalize)
|
||||
```
|
||||
Internal: page (1-indexed), limit
|
||||
API: skip, take (for backend compatibility)
|
||||
UI: page, totalPages, hasNext
|
||||
```
|
||||
|
||||
### 2. Search & Filtering (Unify)
|
||||
```
|
||||
All: Debounced search + filter criteria
|
||||
Pattern: setTimeout 300ms, use AbortController
|
||||
Builder: Construct query string from criteria
|
||||
```
|
||||
|
||||
### 3. Error Handling & Retry (Consolidate)
|
||||
```
|
||||
Retry: Exponential backoff (2^attempt * 1000ms)
|
||||
Retries: 3 attempts max
|
||||
Non-retryable: HTTP 4xx status codes
|
||||
Normalized errors: { message, code, statusCode, details }
|
||||
```
|
||||
|
||||
### 4. Caching Strategy (Add)
|
||||
```
|
||||
IndexedDB: workflowui (persist between sessions, TTL)
|
||||
Memory: frontends/nextjs (session only)
|
||||
HTTP: All (headers-based, ETag support)
|
||||
Manual: invalidate() method on all hooks
|
||||
```
|
||||
|
||||
### 5. Tenancy & Packages (Centralize)
|
||||
```
|
||||
Tenant resolution: Context provider
|
||||
Package routing: Via URL parameters
|
||||
Dependency access: useDependencyEntity pattern
|
||||
Multi-tenant: Automatic tenant ID injection
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Strategy (Phase 5)
|
||||
|
||||
### Timeline: 6-9 weeks (1.5-2 months)
|
||||
|
||||
**Phase 5a: Foundation (1-2 weeks)**
|
||||
- Create base ServiceAdapter interface
|
||||
- Implement Redux, API, DBAL adapters
|
||||
- Create base cache layer
|
||||
- Write adapter tests
|
||||
|
||||
**Phase 5b: Core Hooks (2-3 weeks)**
|
||||
- Implement generic useEntity hook
|
||||
- Create entity-specific hooks (projects, workspaces, workflows, executions, users, packages)
|
||||
- Write hook tests
|
||||
- Create documentation + examples
|
||||
|
||||
**Phase 5c: Migration (2-3 weeks)**
|
||||
- Refactor workflowui hooks to use new pattern
|
||||
- Refactor frontends/nextjs hooks to use new pattern
|
||||
- Add frontends/dbal support
|
||||
- Integration testing across all frontends
|
||||
|
||||
**Phase 5d: Polish (1 week)**
|
||||
- Performance optimization
|
||||
- Cache invalidation improvements
|
||||
- Error handling edge cases
|
||||
- Final documentation + migration guide
|
||||
|
||||
---
|
||||
|
||||
## Implementation Files to Create
|
||||
|
||||
```
|
||||
packages/tier2-hooks/
|
||||
├── src/
|
||||
│ ├── adapters/
|
||||
│ │ ├── base.ts # ServiceAdapter interface
|
||||
│ │ ├── redux-adapter.ts # workflowui
|
||||
│ │ ├── api-adapter.ts # frontends/nextjs
|
||||
│ │ └── dbal-adapter.ts # frontends/dbal
|
||||
│ ├── cache/
|
||||
│ │ ├── index.ts
|
||||
│ │ ├── indexeddb-cache.ts
|
||||
│ │ └── memory-cache.ts
|
||||
│ ├── hooks/
|
||||
│ │ ├── use-entity.ts # Generic hook factory
|
||||
│ │ ├── use-projects.ts
|
||||
│ │ ├── use-workspaces.ts
|
||||
│ │ ├── use-workflows.ts
|
||||
│ │ ├── use-executions.ts
|
||||
│ │ ├── use-users.ts
|
||||
│ │ └── use-packages.ts
|
||||
│ ├── types/
|
||||
│ │ └── index.ts
|
||||
│ └── index.ts
|
||||
├── package.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### Modified Existing Files (Phase 5+)
|
||||
|
||||
**workflowui:**
|
||||
- `src/hooks/useProject.ts` → Use `useEntity` + Redux adapter
|
||||
- `src/hooks/useWorkspace.ts` → Use `useEntity` + Redux adapter
|
||||
- `src/hooks/useWorkflow.ts` → Use `useEntity` + Redux adapter
|
||||
- `src/hooks/useExecution.ts` → Use `useEntity` + Redux adapter
|
||||
|
||||
**frontends/nextjs:**
|
||||
- `src/hooks/useUsers.ts` → Use `useEntity` + API adapter
|
||||
- `src/hooks/usePackages.ts` → Use `useEntity` + API adapter
|
||||
- `src/hooks/useWorkflow.ts` → Use `useEntity` + API adapter
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### Quantitative
|
||||
- 30-40% code reduction (estimated)
|
||||
- Single implementation for 11+ hooks
|
||||
- 100% feature parity across frontends
|
||||
|
||||
### Qualitative
|
||||
- **Developer Experience:** One hook signature to learn
|
||||
- **Consistency:** Same pagination, search, error handling everywhere
|
||||
- **Maintainability:** Bug fixes apply to all hooks automatically
|
||||
- **Scalability:** Add new entities trivially
|
||||
- **Testability:** Mock adapters instead of Redux + services
|
||||
|
||||
---
|
||||
|
||||
## Key Decisions Made
|
||||
|
||||
1. **Adapter Pattern:** Allows incremental migration without breaking changes
|
||||
2. **1-indexed pagination:** Standard for UIs, easier for users
|
||||
3. **Debounce 300ms:** Balances responsiveness and API load
|
||||
4. **No required caching:** Optional via adapter, not forced
|
||||
5. **Multi-tenant from start:** All hooks support tenant resolution
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|------|-----------|--------|-----------|
|
||||
| Redux hooks break during refactor | Medium | High | Gradual migration, run both old+new |
|
||||
| API schema mismatches | Low | High | Adapter layer normalizes differences |
|
||||
| Cache invalidation bugs | Medium | Medium | Comprehensive test suite + manual API |
|
||||
| Performance regression | Low | High | Benchmarking before/after |
|
||||
| Developer confusion during transition | Medium | Low | Migration guide + examples |
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
1. **Code Quality:** 30-40% reduction in Tier 2 hook lines
|
||||
2. **Test Coverage:** >80% on adapters and hooks
|
||||
3. **Type Safety:** Zero `any` types in new code
|
||||
4. **Performance:** <5% API response time regression
|
||||
5. **Documentation:** 100% of hooks documented with examples
|
||||
6. **Adoption:** All frontends migrated by end of Phase 5
|
||||
|
||||
---
|
||||
|
||||
## Immediate Next Steps
|
||||
|
||||
1. ✅ **[DONE]** Analyze existing Tier 2 hooks across codebase
|
||||
2. ✅ **[DONE]** Document patterns and fragmentation
|
||||
3. ✅ **[DONE]** Design unified adapter pattern
|
||||
4. **[TODO]** Present findings to architecture review board
|
||||
5. **[TODO]** Get approval on adapter design
|
||||
6. **[TODO]** Create Phase 5 RFC document
|
||||
7. **[TODO]** Begin Phase 5a: Foundation work
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Hook Inventory by Entity
|
||||
|
||||
### Project Hooks
|
||||
- `useProject()` (workflowui + Redux) - CRUD + current selection
|
||||
- Consolidates to: `useEntity<Project>('project', reduxAdapter)`
|
||||
|
||||
### Workspace Hooks
|
||||
- `useWorkspace()` (workflowui + Redux) - CRUD + current selection
|
||||
- Consolidates to: `useEntity<Workspace>('workspace', reduxAdapter)`
|
||||
|
||||
### Workflow Hooks
|
||||
- `useWorkflow()` (workflowui + Redux) - Load, operations, auto-save
|
||||
- `useWorkflow()` (frontends/nextjs) - Execute with retry + polling
|
||||
- Consolidates to: `useEntity<Workflow>('workflow', adapter)`
|
||||
|
||||
### Execution Hooks
|
||||
- `useExecution()` (workflowui + Redux) - Execute, stop, history, stats
|
||||
- Consolidates to: `useEntity<ExecutionResult>('execution', adapter)`
|
||||
|
||||
### User Hooks
|
||||
- `useUsers()` (frontends/nextjs) - List with pagination + search + filter
|
||||
- `useUserForm()` (frontends/nextjs) - Form management
|
||||
- `useUserActions()` (frontends/nextjs) - CRUD wrapper
|
||||
- Consolidate to: `useEntity<User>('user', apiAdapter)` + `useUserForm()`
|
||||
|
||||
### Package Hooks
|
||||
- `usePackages()` (frontends/nextjs) - List with pagination + search
|
||||
- `usePackageDetails()` (frontends/nextjs) - Single + related
|
||||
- `usePackageActions()` (frontends/nextjs) - CRUD wrapper
|
||||
- Consolidate to: `useEntity<Package>('package', apiAdapter)` + `usePackageDetails()`
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- Full analysis: `/Users/rmac/Documents/metabuilder/docs/TIER2_HOOKS_ANALYSIS.md`
|
||||
- Redux infrastructure docs: `redux/slices/` directory
|
||||
- Service layer docs: `workflowui/src/services/` directory
|
||||
- Frontend-specific patterns: `frontends/nextjs/src/hooks/` directory
|
||||
|
||||
772
docs/TIER2_HOOKS_ANALYSIS.md
Normal file
772
docs/TIER2_HOOKS_ANALYSIS.md
Normal file
@@ -0,0 +1,772 @@
|
||||
# Tier 2 Data Hooks Analysis
|
||||
|
||||
**Analysis Date:** January 23, 2026
|
||||
**Status:** ANALYSIS_COMPLETE
|
||||
**Scope:** Extract and standardize Tier 2 hooks across MetaBuilder frontends
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Tier 2 hooks are entity-level data management hooks that depend on Redux and/or services. They implement CRUD, filtering, pagination, and caching patterns. The analysis reveals significant fragmentation across three frontend implementations (workflowui, frontends/nextjs, codegen) that can be unified through a service adapter pattern.
|
||||
|
||||
---
|
||||
|
||||
## I. Tier 2 Hooks Inventory
|
||||
|
||||
### A. Hooks Found in workflowui (Redux + Service)
|
||||
|
||||
| Hook | Location | Redux Slice | Service | Pattern |
|
||||
|------|----------|------------|---------|---------|
|
||||
| `useProject` | `hooks/useProject.ts` | projectSlice | projectService | CRUD + list + current selection |
|
||||
| `useWorkspace` | `hooks/useWorkspace.ts` | workspaceSlice | workspaceService | CRUD + list + current selection |
|
||||
| `useWorkflow` | `hooks/useWorkflow.ts` | workflowSlice | workflowService | Load, create, auto-save, operations |
|
||||
| `useExecution` | `hooks/useExecution.ts` | workflowSlice | executionService | Execute, stop, history, stats |
|
||||
|
||||
**Characteristics:**
|
||||
- Tightly coupled to Redux state management
|
||||
- Use dispatch/useSelector for state access
|
||||
- Delegate to service layer for API calls
|
||||
- Implement IndexedDB caching via db/schema
|
||||
- Include local storage persistence (tenantId, currentProjectId)
|
||||
|
||||
### B. Hooks Found in frontends/nextjs (No Redux)
|
||||
|
||||
| Hook | Location | Pattern | Caching |
|
||||
|------|----------|---------|---------|
|
||||
| `useUsers` | `hooks/useUsers.ts` | Paginated list + search + filtering | Client state only |
|
||||
| `useWorkflow` | `hooks/useWorkflow.ts` | Execute + polling + retry logic | Client state only |
|
||||
| `usePackages` | `hooks/usePackages.ts` | Paginated list + search + status filter + refetch | Client state only |
|
||||
| `useUserForm` | `hooks/useUserForm.ts` | Form state management | Client state only |
|
||||
| `useUserActions` | `hooks/useUserActions.ts` | CRUD operations wrapper | Client state only |
|
||||
| `usePackageDetails` | `hooks/usePackageDetails.ts` | Single entity + related data | Client state only |
|
||||
| `usePackageActions` | `hooks/usePackageActions.ts` | CRUD operations wrapper | Client state only |
|
||||
|
||||
**Characteristics:**
|
||||
- No Redux dependency
|
||||
- Direct fetch() API calls
|
||||
- Client-side state (useState)
|
||||
- Debounced search
|
||||
- Manual pagination and filtering
|
||||
- AbortController for request cancellation
|
||||
|
||||
### C. Generic Service Adapters (Available to All)
|
||||
|
||||
| Hook | Location | Pattern | Usage |
|
||||
|------|----------|---------|-------|
|
||||
| `useRestApi` | `lib/hooks/use-rest-api.ts` | Generic CRUD with query builder | frontends/nextjs |
|
||||
| `useEntity` | `lib/hooks/use-rest-api.ts` | Entity-specific wrapper | frontends/nextjs |
|
||||
| `useDependencyEntity` | `lib/hooks/use-rest-api.ts` | Cross-package entity access | frontends/nextjs |
|
||||
|
||||
**Characteristics:**
|
||||
- Framework-agnostic API client
|
||||
- Builds URLs from entity name + tenant + package
|
||||
- Supports custom actions
|
||||
- Handles AbortSignal for cancellation
|
||||
- No caching (relies on HTTP caching)
|
||||
|
||||
---
|
||||
|
||||
## II. Common Patterns Identified
|
||||
|
||||
### Pattern 1: Basic CRUD + Current Selection
|
||||
**Examples:** `useProject`, `useWorkspace`
|
||||
**Components:**
|
||||
- State: `items[]`, `currentItem`, `isLoading`, `error`
|
||||
- Actions: `list()`, `create()`, `update()`, `delete()`, `setCurrent()`
|
||||
- Caching: IndexedDB + localStorage for persistence
|
||||
|
||||
### Pattern 2: List with Pagination, Search, Filtering
|
||||
**Examples:** `useUsers`, `usePackages`
|
||||
**Components:**
|
||||
- State: `items[]`, `pagination{page,limit,total}`, `search`, `filters`, `isLoading`
|
||||
- Actions: `fetch()`, `search()`, `filterBy()`, `changePage()`, `changeLimit()`, `refetch()`
|
||||
- Features: Debounced search, AbortController for cancellation
|
||||
- Caching: None (client-side state only)
|
||||
|
||||
### Pattern 3: Entity Operations + Async Actions
|
||||
**Examples:** `useExecution`, `useWorkflow`
|
||||
**Components:**
|
||||
- State: `currentItem`, `history[]`, `status`, `metrics`
|
||||
- Actions: Execute/Action, retrieve results, cancel, retry with backoff
|
||||
- Features: Auto-retry on network errors, progress tracking
|
||||
- Caching: Execution history maintained in Redux/state
|
||||
|
||||
### Pattern 4: Form Management with Actions
|
||||
**Examples:** `useUserForm`, `usePackageActions`
|
||||
**Components:**
|
||||
- State: Form fields, validation errors, submission status
|
||||
- Actions: Update field, validate, submit/delete, reset
|
||||
- Features: Debounced validation, error normalization
|
||||
|
||||
### Pattern 5: Single Entity + Related Data
|
||||
**Examples:** `usePackageDetails`, `useProjectCanvas`
|
||||
**Components:**
|
||||
- State: Main entity, related collections, loading
|
||||
- Actions: Load, refetch, update related items
|
||||
- Caching: None (direct fetch)
|
||||
|
||||
---
|
||||
|
||||
## III. Redux Infrastructure Analysis
|
||||
|
||||
### Redux Slices Used
|
||||
|
||||
**projectSlice** (`redux/slices/src/slices/projectSlice.ts`)
|
||||
```typescript
|
||||
interface ProjectState {
|
||||
projects: Project[]
|
||||
currentProjectId: string | null
|
||||
isLoading: boolean
|
||||
error: string | null
|
||||
}
|
||||
// Actions: setProjects, addProject, updateProject, removeProject, setCurrentProject
|
||||
```
|
||||
|
||||
**workspaceSlice** (`redux/slices/src/slices/workspaceSlice.ts`)
|
||||
```typescript
|
||||
interface WorkspaceState {
|
||||
workspaces: Workspace[]
|
||||
currentWorkspaceId: string | null
|
||||
isLoading: boolean
|
||||
error: string | null
|
||||
}
|
||||
// Actions: similar to projectSlice
|
||||
```
|
||||
|
||||
**workflowSlice** (`redux/slices/src/slices/workflowSlice.ts`)
|
||||
```typescript
|
||||
interface WorkflowState {
|
||||
current: Workflow | null
|
||||
nodes: WorkflowNode[]
|
||||
connections: WorkflowConnection[]
|
||||
isDirty: boolean
|
||||
isSaving: boolean
|
||||
executionHistory: ExecutionResult[]
|
||||
currentExecution: ExecutionResult | null
|
||||
}
|
||||
// Actions: loadWorkflow, addNode, updateNode, deleteNode, addConnection, startExecution, endExecution
|
||||
```
|
||||
|
||||
**Key Selectors Pattern:**
|
||||
```typescript
|
||||
export const selectProjects = (state: { project: ProjectState }) => state.project.projects
|
||||
export const selectCurrentProject = (state: { project: ProjectState }) => {
|
||||
if (!state.project.currentProjectId) return null
|
||||
return state.project.projects.find((p) => p.id === state.project.currentProjectId)
|
||||
}
|
||||
```
|
||||
|
||||
### Redux in Hooks Pattern
|
||||
|
||||
**Workflowui pattern:**
|
||||
```typescript
|
||||
const dispatch = useDispatch<AppDispatch>()
|
||||
const items = useSelector((state: RootState) => selectItems(state))
|
||||
const isLoading = useSelector((state: RootState) => selectIsLoading(state))
|
||||
|
||||
const load = useCallback(async () => {
|
||||
dispatch(setLoading(true))
|
||||
try {
|
||||
const data = await service.list()
|
||||
dispatch(setItems(data))
|
||||
} finally {
|
||||
dispatch(setLoading(false))
|
||||
}
|
||||
}, [dispatch])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## IV. Service Layer Analysis
|
||||
|
||||
### Service Base Structure
|
||||
|
||||
All services follow this pattern:
|
||||
|
||||
```typescript
|
||||
const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:5000/api'
|
||||
|
||||
async function apiRequest<T>(
|
||||
endpoint: string,
|
||||
options: RequestInit & { retries?: number; params?: Record<string, any> }
|
||||
): Promise<T>
|
||||
|
||||
export const service = {
|
||||
// CRUD operations
|
||||
async list(tenantId, params) { }
|
||||
async get(id) { }
|
||||
async create(data) { }
|
||||
async update(id, data) { }
|
||||
async delete(id) { }
|
||||
|
||||
// Optional: specialized operations
|
||||
async customAction() { }
|
||||
}
|
||||
```
|
||||
|
||||
### Services Found
|
||||
|
||||
| Service | Location | Entities |
|
||||
|---------|----------|----------|
|
||||
| projectService | `workflowui/src/services/projectService.ts` | projects, canvas items |
|
||||
| workspaceService | `workflowui/src/services/workspaceService.ts` | workspaces |
|
||||
| workflowService | `workflowui/src/services/workflowService.ts` | workflows |
|
||||
| executionService | `workflowui/src/services/executionService.ts` | executions |
|
||||
|
||||
---
|
||||
|
||||
## V. Common Implementation Details
|
||||
|
||||
### Local Storage Usage
|
||||
```typescript
|
||||
// Pattern across hooks:
|
||||
const getTenantId = useCallback(() => {
|
||||
return localStorage.getItem('tenantId') || 'default'
|
||||
}, [])
|
||||
|
||||
localStorage.setItem('currentProjectId', id)
|
||||
localStorage.removeItem('currentProjectId')
|
||||
```
|
||||
|
||||
### IndexedDB Caching (workflowui only)
|
||||
```typescript
|
||||
// Pattern:
|
||||
import { projectDB, workspaceDB } from '../db/schema'
|
||||
|
||||
await projectDB.create(project)
|
||||
await projectDB.update(project)
|
||||
await projectDB.delete(id)
|
||||
```
|
||||
|
||||
### Debouncing (frontends/nextjs pattern)
|
||||
```typescript
|
||||
// Global timer for search
|
||||
let searchTimeout: NodeJS.Timeout | null = null
|
||||
|
||||
const search = useCallback((term) => {
|
||||
if (searchTimeout) clearTimeout(searchTimeout)
|
||||
setState(prev => ({ ...prev, search: term }))
|
||||
|
||||
searchTimeout = setTimeout(async () => {
|
||||
await fetchUsers(1, limit, term)
|
||||
}, 300)
|
||||
}, [])
|
||||
```
|
||||
|
||||
### AbortController Pattern (frontends/nextjs)
|
||||
```typescript
|
||||
const abortControllerRef = useRef<AbortController | null>(null)
|
||||
|
||||
const fetch = useCallback(async () => {
|
||||
if (abortControllerRef.current) {
|
||||
abortControllerRef.current.abort()
|
||||
}
|
||||
|
||||
abortControllerRef.current = new AbortController()
|
||||
|
||||
try {
|
||||
const response = await fetch(url, {
|
||||
signal: abortControllerRef.current.signal
|
||||
})
|
||||
} catch (err) {
|
||||
if (err instanceof Error && err.name === 'AbortError') return
|
||||
}
|
||||
}, [])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VI. Proposed Service Adapter Pattern
|
||||
|
||||
### Goal
|
||||
Create a unified Tier 2 hook interface that works with or without Redux, supports optional caching, and provides consistent CRUD patterns.
|
||||
|
||||
### Architecture Design
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ React Component (Any Frontend) │
|
||||
└────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Tier 2 Hooks (Standardized API) │
|
||||
│ useEntity<T>(entityType, options) | useUsers() etc. │
|
||||
└────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────┴────────────────┐
|
||||
▼ ▼
|
||||
┌──────────────────────┐ ┌──────────────────────┐
|
||||
│ Redux Adapter │ │ Direct API Adapter │
|
||||
│ (with dispatch) │ │ (no Redux) │
|
||||
└──────────────────────┘ └──────────────────────┘
|
||||
│ │
|
||||
└────────────────┬────────────────┘
|
||||
▼
|
||||
┌────────────────────────────────┐
|
||||
│ Service Layer (Generic) │
|
||||
│ - API calls (fetch) │
|
||||
│ - Retry logic │
|
||||
│ - Query building │
|
||||
└────────────────────────────────┘
|
||||
│
|
||||
┌────────────────┴────────────────┐
|
||||
▼ ▼
|
||||
┌──────────────────────┐ ┌──────────────────────┐
|
||||
│ Optional Cache │ │ HTTP Cache │
|
||||
│ (IndexedDB) │ │ (Headers) │
|
||||
└──────────────────────┘ └──────────────────────┘
|
||||
```
|
||||
|
||||
### Adapter Interface Specification
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Adapter configuration - determines data source strategy
|
||||
*/
|
||||
interface DataSourceAdapter<T> {
|
||||
// Whether to use Redux for state management
|
||||
useRedux: boolean
|
||||
|
||||
// Redux integration (optional)
|
||||
redux?: {
|
||||
dispatch: AppDispatch
|
||||
selectState: (state: RootState) => EntityState<T>
|
||||
actions: {
|
||||
setLoading: (loading: boolean) => Action
|
||||
setError: (error: string | null) => Action
|
||||
setItems: (items: T[]) => Action
|
||||
addItem: (item: T) => Action
|
||||
updateItem: (item: T) => Action
|
||||
removeItem: (id: string) => Action
|
||||
setCurrent: (id: string | null) => Action
|
||||
}
|
||||
}
|
||||
|
||||
// Cache strategy
|
||||
cache?: {
|
||||
type: 'indexeddb' | 'localstorage' | 'memory' | 'none'
|
||||
ttl?: number // milliseconds
|
||||
}
|
||||
|
||||
// API configuration
|
||||
api: {
|
||||
baseUrl: string
|
||||
tenant?: string
|
||||
retries?: number
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Standardized Tier 2 hook return type
|
||||
*/
|
||||
interface UseEntityReturn<T> {
|
||||
// State
|
||||
items: T[]
|
||||
currentItem: T | null
|
||||
currentId: string | null
|
||||
isLoading: boolean
|
||||
error: string | null
|
||||
pagination?: {
|
||||
page: number
|
||||
limit: number
|
||||
total: number
|
||||
totalPages: number
|
||||
}
|
||||
|
||||
// CRUD actions
|
||||
list: (options?: FetchOptions) => Promise<T[]>
|
||||
get: (id: string) => Promise<T | null>
|
||||
create: (data: Partial<T>) => Promise<T>
|
||||
update: (id: string, data: Partial<T>) => Promise<T>
|
||||
delete: (id: string) => Promise<void>
|
||||
|
||||
// Convenience actions
|
||||
setCurrent: (id: string | null) => void
|
||||
refetch: () => Promise<void>
|
||||
|
||||
// Search & filter
|
||||
search?: (term: string) => Promise<void>
|
||||
filter?: (criteria: Record<string, any>) => Promise<void>
|
||||
}
|
||||
|
||||
/**
|
||||
* Factory function - creates properly configured hook
|
||||
*/
|
||||
function createTier2Hook<T>(config: {
|
||||
entityType: string
|
||||
adapter: DataSourceAdapter<T>
|
||||
}): () => UseEntityReturn<T>
|
||||
```
|
||||
|
||||
### Implementation Strategy: Three Adapter Types
|
||||
|
||||
#### Adapter 1: Redux-Backed (workflowui)
|
||||
```typescript
|
||||
const useProjectWithRedux = () => {
|
||||
const adapter = {
|
||||
useRedux: true,
|
||||
redux: {
|
||||
dispatch: useDispatch(),
|
||||
selectState: (state) => state.project,
|
||||
actions: projectSlice.actions
|
||||
},
|
||||
cache: { type: 'indexeddb' },
|
||||
api: { baseUrl: '/api', tenant: getTenantId() }
|
||||
}
|
||||
|
||||
return createTier2Hook({
|
||||
entityType: 'project',
|
||||
adapter
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
#### Adapter 2: Direct API (frontends/nextjs)
|
||||
```typescript
|
||||
const useUsersWithAPI = () => {
|
||||
const adapter = {
|
||||
useRedux: false,
|
||||
cache: { type: 'memory' },
|
||||
api: {
|
||||
baseUrl: '/api/v1/{tenant}',
|
||||
tenant: getTenant()
|
||||
}
|
||||
}
|
||||
|
||||
return createTier2Hook({
|
||||
entityType: 'user',
|
||||
adapter
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
#### Adapter 3: Minimal DBAL (frontends/dbal)
|
||||
```typescript
|
||||
const useEntitiesWithDBAL = () => {
|
||||
const adapter = {
|
||||
useRedux: false,
|
||||
cache: { type: 'none' },
|
||||
api: {
|
||||
baseUrl: '/api/v1/{tenant}',
|
||||
retries: 1
|
||||
}
|
||||
}
|
||||
|
||||
return createTier2Hook({
|
||||
entityType: 'entity',
|
||||
adapter
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VII. Standardized Features to Extract
|
||||
|
||||
### A. Pagination Pattern
|
||||
**Standardize:** Skip/take parameters, total count, page calculation
|
||||
|
||||
**Current fragmentation:**
|
||||
- workflowui: `limit`, `offset`, `params`
|
||||
- frontends/nextjs: `page`, `limit` (0-indexed)
|
||||
- useRestApi: `take`, `skip`
|
||||
|
||||
**Unified approach:**
|
||||
```typescript
|
||||
interface PaginationOptions {
|
||||
page: number // 1-indexed
|
||||
limit: number // items per page
|
||||
}
|
||||
|
||||
// Convert to API params (skip/take)
|
||||
const apiParams = {
|
||||
skip: (page - 1) * limit,
|
||||
take: limit
|
||||
}
|
||||
```
|
||||
|
||||
### B. Search & Filter Pattern
|
||||
**Standardize:** Debounced search, multi-field filtering, query building
|
||||
|
||||
**Current implementation:**
|
||||
```typescript
|
||||
// frontends/nextjs useUsers
|
||||
const searchUsers = useCallback(async (term) => {
|
||||
if (searchTimeout) clearTimeout(searchTimeout)
|
||||
setState(prev => ({ ...prev, search: term }))
|
||||
|
||||
searchTimeout = setTimeout(async () => {
|
||||
await fetchUsers(1, limit, term)
|
||||
}, 300)
|
||||
}, [])
|
||||
|
||||
// Should be unified as:
|
||||
const search = useCallback((term, options?) => {
|
||||
return debounceSearch(term, 300, async (t) => {
|
||||
await list({ search: t, page: 1 })
|
||||
})
|
||||
}, [])
|
||||
```
|
||||
|
||||
### C. Error Handling & Retry Pattern
|
||||
**Standardize:** Exponential backoff, retry logic, error normalization
|
||||
|
||||
**Current pattern in projectService:**
|
||||
```typescript
|
||||
for (let attempt = 0; attempt < retries; attempt++) {
|
||||
try {
|
||||
const response = await fetch(url, options)
|
||||
if (!response.ok) throw new Error(...)
|
||||
return response.json()
|
||||
} catch (error) {
|
||||
if (attempt < retries - 1 && !(error as any).status) {
|
||||
await new Promise(resolve =>
|
||||
setTimeout(resolve, Math.pow(2, attempt) * 1000)
|
||||
)
|
||||
continue
|
||||
}
|
||||
throw lastError
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Should extract to:** `retryWithBackoff(fn, options)`
|
||||
|
||||
### D. Cache Invalidation Strategy
|
||||
**Standardize:** TTL-based, manual invalidation, optimistic updates
|
||||
|
||||
**Options:**
|
||||
- IndexedDB: Persist between sessions, TTL checking
|
||||
- Memory: Session-only, instant invalidation
|
||||
- HTTP headers: ETags, Cache-Control
|
||||
|
||||
### E. Tenancy & Multi-Package Support
|
||||
**Standardize:** Tenant resolution, package routing, dependency access
|
||||
|
||||
**Pattern:**
|
||||
```typescript
|
||||
const getTenantId = useCallback(() => {
|
||||
return localStorage.getItem('tenantId') || 'default'
|
||||
}, [])
|
||||
|
||||
// Should be centralized:
|
||||
const { tenant, package, hasPackage } = useTenantContext()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VIII. Migration Path: Phase 5 Implementation
|
||||
|
||||
### Step 1: Create Base Service Adapter Layer
|
||||
**File:** `packages/tier2-hooks/src/adapters/base.ts`
|
||||
```typescript
|
||||
export interface ServiceAdapter<T> {
|
||||
list(options?: FetchOptions): Promise<T[]>
|
||||
get(id: string): Promise<T | null>
|
||||
create(data: Partial<T>): Promise<T>
|
||||
update(id: string, data: Partial<T>): Promise<T>
|
||||
delete(id: string): Promise<void>
|
||||
}
|
||||
|
||||
export class BaseServiceAdapter<T> implements ServiceAdapter<T> {
|
||||
// Implement retry logic, query building, error handling
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Create Adapter Implementations
|
||||
**Files:**
|
||||
- `packages/tier2-hooks/src/adapters/redux-adapter.ts` (for workflowui)
|
||||
- `packages/tier2-hooks/src/adapters/api-adapter.ts` (for frontends/nextjs)
|
||||
- `packages/tier2-hooks/src/adapters/dbal-adapter.ts` (for frontends/dbal)
|
||||
|
||||
### Step 3: Implement Unified Tier 2 Hooks
|
||||
**File:** `packages/tier2-hooks/src/hooks/use-entity.ts`
|
||||
```typescript
|
||||
export function useEntity<T>(
|
||||
entityType: string,
|
||||
adapter: ServiceAdapter<T>,
|
||||
options?: EntityOptions<T>
|
||||
): UseEntityReturn<T>
|
||||
```
|
||||
|
||||
### Step 4: Create Entity-Specific Hooks
|
||||
**Files:**
|
||||
- `packages/tier2-hooks/src/hooks/use-projects.ts`
|
||||
- `packages/tier2-hooks/src/hooks/use-workspaces.ts`
|
||||
- `packages/tier2-hooks/src/hooks/use-workflows.ts`
|
||||
- `packages/tier2-hooks/src/hooks/use-executions.ts`
|
||||
- `packages/tier2-hooks/src/hooks/use-users.ts`
|
||||
- `packages/tier2-hooks/src/hooks/use-packages.ts`
|
||||
|
||||
### Step 5: Refactor Existing Hooks (Per Frontend)
|
||||
- **workflowui:** Update to use new unified hooks (with Redux adapter)
|
||||
- **frontends/nextjs:** Update to use new unified hooks (with API adapter)
|
||||
- **frontends/dbal:** Use new unified hooks (with minimal adapter)
|
||||
|
||||
### Step 6: Add Cache Layer (Optional)
|
||||
**File:** `packages/tier2-hooks/src/cache/index.ts`
|
||||
- IndexedDB cache for workflowui
|
||||
- Memory cache for frontends
|
||||
- Cache invalidation strategies
|
||||
|
||||
---
|
||||
|
||||
## IX. Benefits of Unified Approach
|
||||
|
||||
### For Developers
|
||||
1. **Single API:** One hook signature across all frontends
|
||||
2. **Consistency:** Same pagination, search, error handling everywhere
|
||||
3. **Reusability:** Generic hooks work with any entity type
|
||||
4. **Testability:** Adapters enable easier mocking and testing
|
||||
|
||||
### For Deployments
|
||||
1. **Code Reduction:** ~40% less code (estimated)
|
||||
2. **Maintainability:** Single source of truth for entity patterns
|
||||
3. **Scalability:** Easy to add new entities or frontends
|
||||
4. **Performance:** Standardized caching strategies
|
||||
|
||||
### For Product Features
|
||||
1. **Feature Parity:** All frontends get same capabilities
|
||||
2. **Real-time Sync:** Easier to add WebSocket/real-time adapters
|
||||
3. **Offline Support:** Cache layer enables offline mode
|
||||
4. **Analytics:** Centralized API call tracking
|
||||
|
||||
---
|
||||
|
||||
## X. Risks & Mitigation
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|-----------|
|
||||
| Redux hooks strongly coupled to slices | Create slim adapter layer that doesn't break existing Redux |
|
||||
| Different API schemas per frontend | Normalize at adapter layer before returning data |
|
||||
| Pagination index differences (0 vs 1) | Convert internally; expose 1-indexed to consumers |
|
||||
| Cache invalidation bugs | Comprehensive test suite + manual invalidation API |
|
||||
| Breaking existing code | Gradual migration; run both old and new hooks during transition |
|
||||
|
||||
---
|
||||
|
||||
## XI. Dependencies
|
||||
|
||||
### Required Packages
|
||||
- `@reduxjs/toolkit` (already in workflowui)
|
||||
- `react` (already in all frontends)
|
||||
- No new external dependencies needed
|
||||
|
||||
### Internal Dependencies
|
||||
- Redux slices (from redux/slices)
|
||||
- Service implementations (from each frontend)
|
||||
- Type definitions (consolidate to packages/types)
|
||||
|
||||
---
|
||||
|
||||
## XII. Files to Create/Modify
|
||||
|
||||
### New Files (Phase 5)
|
||||
```
|
||||
packages/
|
||||
├── tier2-hooks/ # New package
|
||||
│ ├── src/
|
||||
│ │ ├── adapters/
|
||||
│ │ │ ├── base.ts
|
||||
│ │ │ ├── redux-adapter.ts
|
||||
│ │ │ ├── api-adapter.ts
|
||||
│ │ │ └── dbal-adapter.ts
|
||||
│ │ ├── cache/
|
||||
│ │ │ ├── index.ts
|
||||
│ │ │ ├── indexeddb-cache.ts
|
||||
│ │ │ └── memory-cache.ts
|
||||
│ │ ├── hooks/
|
||||
│ │ │ ├── use-entity.ts
|
||||
│ │ │ ├── use-projects.ts
|
||||
│ │ │ ├── use-workspaces.ts
|
||||
│ │ │ ├── use-workflows.ts
|
||||
│ │ │ ├── use-executions.ts
|
||||
│ │ │ ├── use-users.ts
|
||||
│ │ │ └── use-packages.ts
|
||||
│ │ ├── types/
|
||||
│ │ │ └── index.ts
|
||||
│ │ └── index.ts
|
||||
│ ├── package.json
|
||||
│ └── README.md
|
||||
```
|
||||
|
||||
### Modified Files (Phase 5+)
|
||||
- `workflowui/src/hooks/useProject.ts` → Use new unified hook
|
||||
- `workflowui/src/hooks/useWorkspace.ts` → Use new unified hook
|
||||
- `workflowui/src/hooks/useWorkflow.ts` → Use new unified hook
|
||||
- `workflowui/src/hooks/useExecution.ts` → Use new unified hook
|
||||
- `frontends/nextjs/src/hooks/useUsers.ts` → Use new unified hook
|
||||
- `frontends/nextjs/src/hooks/usePackages.ts` → Use new unified hook
|
||||
- `frontends/nextjs/src/hooks/useWorkflow.ts` → Use new unified hook
|
||||
|
||||
---
|
||||
|
||||
## XIII. Estimation
|
||||
|
||||
### Phase 5a: Foundation (1-2 weeks)
|
||||
- Create base adapter layer
|
||||
- Define types and interfaces
|
||||
- Implement 3 adapter variants
|
||||
- Write tests for adapters
|
||||
|
||||
### Phase 5b: Core Hooks (2-3 weeks)
|
||||
- Implement generic useEntity hook
|
||||
- Create entity-specific hooks
|
||||
- Write tests for hooks
|
||||
- Documentation
|
||||
|
||||
### Phase 5c: Migration (2-3 weeks)
|
||||
- Refactor workflowui hooks
|
||||
- Refactor frontends/nextjs hooks
|
||||
- Add dbal support
|
||||
- Integration testing
|
||||
|
||||
### Phase 5d: Polish (1 week)
|
||||
- Performance optimization
|
||||
- Cache invalidation strategies
|
||||
- Error handling improvements
|
||||
- Final documentation
|
||||
|
||||
**Total Estimate:** 6-9 weeks (1.5-2 months)
|
||||
|
||||
---
|
||||
|
||||
## XIV. Success Metrics
|
||||
|
||||
1. **Code Reduction:** 30-40% fewer hooks files
|
||||
2. **Coverage:** 100% of entity CRUD operations
|
||||
3. **Test Coverage:** >80% on adapters and hooks
|
||||
4. **Performance:** <5% regression in API response times
|
||||
5. **Type Safety:** All hooks fully typed, no `any` types
|
||||
6. **Documentation:** All hooks documented with examples
|
||||
|
||||
---
|
||||
|
||||
## XV. Next Steps
|
||||
|
||||
1. **Review this analysis** with team leads
|
||||
2. **Validate proposed adapter pattern** against actual use cases
|
||||
3. **Create proof-of-concept** with one entity (e.g., useProjects)
|
||||
4. **Iterate based on feedback**
|
||||
5. **Plan Phase 5 work in detail**
|
||||
6. **Create RFC document** for architecture review
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Hook Comparison Matrix
|
||||
|
||||
| Feature | workflowui | frontends/nextjs | codegen |
|
||||
|---------|-----------|-----------------|---------|
|
||||
| Redux support | ✅ Yes | ❌ No | ⚠️ Partial |
|
||||
| Service layer | ✅ Yes | ⚠️ Direct fetch | ❌ No |
|
||||
| Pagination | ⚠️ limit/offset | ✅ page/limit | ❌ None |
|
||||
| Search | ❌ No | ✅ Debounced | ❌ No |
|
||||
| Filtering | ❌ No | ✅ Yes | ❌ No |
|
||||
| Retry logic | ✅ Yes | ❌ No | ❌ No |
|
||||
| Caching | ✅ IndexedDB | ❌ No | ❌ No |
|
||||
| Refetch on focus | ❌ No | ✅ Yes | ❌ No |
|
||||
| Form management | ⚠️ Partial | ✅ Yes | ❌ No |
|
||||
| Current selection | ✅ Yes | ❌ No | ❌ No |
|
||||
| Error handling | ✅ Yes | ⚠️ Basic | ❌ No |
|
||||
| Type safety | ✅ Strong | ✅ Strong | ⚠️ Weak |
|
||||
|
||||
410
docs/TIER2_HOOKS_REFERENCE.md
Normal file
410
docs/TIER2_HOOKS_REFERENCE.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# Tier 2 Hooks Quick Reference
|
||||
|
||||
**Last Updated:** January 23, 2026
|
||||
**Analysis Status:** COMPLETE
|
||||
|
||||
---
|
||||
|
||||
## Hooks Inventory
|
||||
|
||||
### Tier 2 Hooks by Frontend
|
||||
|
||||
#### workflowui (4 hooks - Redux + Service + IndexedDB)
|
||||
| Hook | File | Redux Slice | Service | Caching |
|
||||
|------|------|------------|---------|---------|
|
||||
| useProject | `hooks/useProject.ts` | projectSlice | projectService | IndexedDB |
|
||||
| useWorkspace | `hooks/useWorkspace.ts` | workspaceSlice | workspaceService | IndexedDB |
|
||||
| useWorkflow | `hooks/useWorkflow.ts` | workflowSlice | workflowService | Redux state |
|
||||
| useExecution | `hooks/useExecution.ts` | workflowSlice | executionService | Redux state |
|
||||
|
||||
#### frontends/nextjs (7 hooks - Direct API + useState)
|
||||
| Hook | File | Service | Caching | Features |
|
||||
|------|------|---------|---------|----------|
|
||||
| useUsers | `hooks/useUsers.ts` | Direct fetch | None | Pagination, search, filter |
|
||||
| useUserForm | `hooks/useUserForm.ts` | Direct fetch | None | Form state, validation |
|
||||
| useUserActions | `hooks/useUserActions.ts` | Direct fetch | None | CRUD operations |
|
||||
| usePackages | `hooks/usePackages.ts` | Direct fetch | None | Pagination, search, status filter |
|
||||
| usePackageDetails | `hooks/usePackageDetails.ts` | Direct fetch | None | Single entity + relations |
|
||||
| usePackageActions | `hooks/usePackageActions.ts` | Direct fetch | None | CRUD operations |
|
||||
| useWorkflow | `hooks/useWorkflow.ts` | Direct fetch | None | Execute, retry, polling |
|
||||
|
||||
#### Generic Adapters (3 - frontends/nextjs)
|
||||
| Hook | File | Purpose |
|
||||
|------|------|---------|
|
||||
| useRestApi | `lib/hooks/use-rest-api.ts` | Generic CRUD builder |
|
||||
| useEntity | `lib/hooks/use-rest-api.ts` | Entity-specific wrapper |
|
||||
| useDependencyEntity | `lib/hooks/use-rest-api.ts` | Cross-package access |
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns (5)
|
||||
|
||||
### Pattern 1: Basic CRUD + Selection
|
||||
```typescript
|
||||
// State: items[], current, isLoading, error
|
||||
// Actions: list(), create(), update(), delete(), setCurrent()
|
||||
// Examples: useProject, useWorkspace
|
||||
```
|
||||
|
||||
### Pattern 2: List + Pagination + Search + Filter
|
||||
```typescript
|
||||
// State: items[], pagination{page,limit,total}, search, filters, isLoading
|
||||
// Actions: fetch(), search(), filterBy(), changePage(), changeLimit(), refetch()
|
||||
// Features: Debounced search (300ms), AbortController cancellation
|
||||
// Examples: useUsers, usePackages
|
||||
```
|
||||
|
||||
### Pattern 3: Async Action + History + Stats
|
||||
```typescript
|
||||
// State: currentItem, history[], status, metrics, isLoading
|
||||
// Actions: execute(), stop(), getHistory(), getStats()
|
||||
// Features: Auto-retry (3 attempts), progress tracking, polling
|
||||
// Examples: useExecution, useWorkflow(frontends/nextjs)
|
||||
```
|
||||
|
||||
### Pattern 4: Form Management + Actions
|
||||
```typescript
|
||||
// State: formData, errors, isDirty, isSubmitting
|
||||
// Actions: updateField(), validate(), submit(), delete(), reset()
|
||||
// Features: Debounced validation, error normalization
|
||||
// Examples: useUserForm, usePackageActions
|
||||
```
|
||||
|
||||
### Pattern 5: Single Entity + Related Collections
|
||||
```typescript
|
||||
// State: main, relations{}, isLoading, error
|
||||
// Actions: load(), refetch(), updateRelated()
|
||||
// Features: Lazy loading, optional relations
|
||||
// Examples: usePackageDetails, useProjectCanvas
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Unified Hook Signature (Phase 5 Target)
|
||||
|
||||
```typescript
|
||||
// Generic hook
|
||||
useEntity<T>(entityType: string, options?: {
|
||||
adapter: 'redux' | 'api' | 'dbal'
|
||||
tenant?: string
|
||||
cache?: boolean | { type: 'indexeddb' | 'memory' | 'none', ttl?: number }
|
||||
}): UseEntityReturn<T>
|
||||
|
||||
// Return type (all frontends)
|
||||
interface UseEntityReturn<T> {
|
||||
items: T[]
|
||||
currentItem: T | null
|
||||
isLoading: boolean
|
||||
error: string | null
|
||||
pagination?: { page: number, limit: number, total: number, totalPages: number }
|
||||
|
||||
list(options?: { page?, limit?, search?, filter? }): Promise<T[]>
|
||||
get(id: string): Promise<T | null>
|
||||
create(data: Partial<T>): Promise<T>
|
||||
update(id: string, data: Partial<T>): Promise<T>
|
||||
delete(id: string): Promise<void>
|
||||
setCurrent(id: string | null): void
|
||||
refetch(): Promise<void>
|
||||
search?(term: string): Promise<void>
|
||||
filter?(criteria: Record<string, any>): Promise<void>
|
||||
}
|
||||
|
||||
// Entity-specific hooks
|
||||
useProjects(options?): UseEntityReturn<Project>
|
||||
useWorkspaces(options?): UseEntityReturn<Workspace>
|
||||
useWorkflows(options?): UseEntityReturn<Workflow>
|
||||
useExecutions(options?): UseEntityReturn<ExecutionResult>
|
||||
useUsers(options?): UseEntityReturn<User>
|
||||
usePackages(options?): UseEntityReturn<Package>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Implementation Details
|
||||
|
||||
### Pagination Normalization
|
||||
```
|
||||
Current fragmentation:
|
||||
workflowui: limit, offset
|
||||
frontends/nextjs: page (0-indexed), limit
|
||||
useRestApi: skip, take
|
||||
|
||||
Unified approach:
|
||||
External API: page (1-indexed), limit
|
||||
Internal API: skip = (page - 1) * limit, take = limit
|
||||
```
|
||||
|
||||
### Search & Filter Pattern
|
||||
```typescript
|
||||
// All hooks should support:
|
||||
const { search, filter } = useEntity('user')
|
||||
|
||||
// Debounced search (300ms)
|
||||
await search('john')
|
||||
|
||||
// Structured filtering
|
||||
await filter({ role: 'admin', status: 'active' })
|
||||
|
||||
// Combined with pagination
|
||||
await list({ page: 1, limit: 10, search: 'john', filter: {...} })
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
```typescript
|
||||
// Retry strategy
|
||||
- Exponential backoff: 2^attempt * 1000ms
|
||||
- Max retries: 3
|
||||
- Non-retryable: 4xx status codes
|
||||
|
||||
// Error structure
|
||||
interface EntityError {
|
||||
message: string
|
||||
code: string
|
||||
statusCode?: number
|
||||
details?: Record<string, any>
|
||||
}
|
||||
```
|
||||
|
||||
### Caching
|
||||
```typescript
|
||||
// IndexedDB (workflowui)
|
||||
- Persist between sessions
|
||||
- TTL: 24 hours (configurable)
|
||||
- Manual invalidation: invalidateCache()
|
||||
|
||||
// Memory (frontends/nextjs optional)
|
||||
- Session-only cache
|
||||
- TTL: 5 minutes (configurable)
|
||||
- Cleared on page reload
|
||||
|
||||
// HTTP (all)
|
||||
- ETag-based
|
||||
- Cache-Control headers
|
||||
- Conditional requests
|
||||
```
|
||||
|
||||
### Tenancy
|
||||
```typescript
|
||||
// Automatic tenant resolution
|
||||
const getTenantId = () => localStorage.getItem('tenantId') || 'default'
|
||||
|
||||
// Should centralize in context:
|
||||
const { tenant, package } = useTenantContext()
|
||||
|
||||
// Multi-package support
|
||||
const { list: listRoles } = useDependencyEntity('user_manager', 'roles')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Service Architecture
|
||||
|
||||
### Base Service Pattern
|
||||
```typescript
|
||||
async function apiRequest<T>(
|
||||
endpoint: string,
|
||||
options: {
|
||||
method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
|
||||
body?: any
|
||||
params?: Record<string, any>
|
||||
retries?: number
|
||||
}
|
||||
): Promise<T>
|
||||
|
||||
// Built with:
|
||||
// - Retry logic (exponential backoff)
|
||||
// - Query parameter building
|
||||
// - Error normalization
|
||||
// - JSON serialization
|
||||
```
|
||||
|
||||
### Services Found
|
||||
| Service | Entities |
|
||||
|---------|----------|
|
||||
| projectService | projects, canvas items |
|
||||
| workspaceService | workspaces |
|
||||
| workflowService | workflows, validation, metrics |
|
||||
| executionService | executions, history, stats |
|
||||
|
||||
---
|
||||
|
||||
## Redux Integration (workflowui)
|
||||
|
||||
### Slice Structure
|
||||
```typescript
|
||||
interface EntityState {
|
||||
items: Entity[]
|
||||
currentId: string | null
|
||||
isLoading: boolean
|
||||
error: string | null
|
||||
}
|
||||
|
||||
// Actions provided by each slice
|
||||
- setLoading(bool)
|
||||
- setError(string | null)
|
||||
- setItems(Entity[])
|
||||
- addItem(Entity)
|
||||
- updateItem(Entity)
|
||||
- removeItem(id)
|
||||
- setCurrent(id)
|
||||
|
||||
// Selectors
|
||||
- selectItems(state)
|
||||
- selectCurrent(state)
|
||||
- selectCurrentId(state)
|
||||
- selectIsLoading(state)
|
||||
- selectError(state)
|
||||
```
|
||||
|
||||
### Hook Integration Pattern
|
||||
```typescript
|
||||
const dispatch = useDispatch()
|
||||
const items = useSelector(selectItems)
|
||||
const isLoading = useSelector(selectIsLoading)
|
||||
|
||||
const list = useCallback(async () => {
|
||||
dispatch(setLoading(true))
|
||||
try {
|
||||
const data = await service.list()
|
||||
dispatch(setItems(data))
|
||||
} finally {
|
||||
dispatch(setLoading(false))
|
||||
}
|
||||
}, [dispatch])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints Structure
|
||||
|
||||
### Standard REST Paths
|
||||
```
|
||||
GET /api/v1/{tenant}/{package}/{entity}
|
||||
- List with pagination: ?skip=0&take=20
|
||||
- With search: ?search=term
|
||||
- With filter: ?status=active
|
||||
|
||||
GET /api/v1/{tenant}/{package}/{entity}/{id}
|
||||
- Get single entity
|
||||
|
||||
POST /api/v1/{tenant}/{package}/{entity}
|
||||
- Create (body: entity data)
|
||||
|
||||
PUT /api/v1/{tenant}/{package}/{entity}/{id}
|
||||
- Update (body: partial entity)
|
||||
|
||||
DELETE /api/v1/{tenant}/{package}/{entity}/{id}
|
||||
- Delete
|
||||
|
||||
POST /api/v1/{tenant}/{package}/{entity}/{id}/{action}
|
||||
- Custom action (body: action parameters)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Features Comparison Matrix
|
||||
|
||||
| Feature | workflowui | frontends/nextjs | codegen | Phase 5 |
|
||||
|---------|-----------|-----------------|---------|---------|
|
||||
| CRUD | ✅ | ✅ | ⚠️ | ✅ |
|
||||
| Redux | ✅ | ❌ | ⚠️ | ✅ |
|
||||
| Pagination | ⚠️ | ✅ | ❌ | ✅ |
|
||||
| Search | ❌ | ✅ | ❌ | ✅ |
|
||||
| Filter | ❌ | ✅ | ❌ | ✅ |
|
||||
| Retry | ✅ | ❌ | ❌ | ✅ |
|
||||
| Cache | ✅ | ❌ | ❌ | ✅ |
|
||||
| Refetch | ❌ | ✅ | ❌ | ✅ |
|
||||
| Current selection | ✅ | ❌ | ❌ | ✅ |
|
||||
| Type safety | ✅ | ✅ | ⚠️ | ✅ |
|
||||
| Error handling | ✅ | ⚠️ | ❌ | ✅ |
|
||||
|
||||
Legend: ✅ Full support | ⚠️ Partial/inconsistent | ❌ Not supported
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 Deliverables
|
||||
|
||||
### Code
|
||||
- `packages/tier2-hooks/` - New unified package
|
||||
- Adapters: Redux, API, DBAL
|
||||
- Hooks: useEntity, useProjects, useWorkspaces, etc.
|
||||
- Cache: IndexedDB, memory implementations
|
||||
|
||||
### Documentation
|
||||
- API reference
|
||||
- Migration guide (old → new hooks)
|
||||
- Examples for each frontend
|
||||
- Adapter architecture docs
|
||||
|
||||
### Tests
|
||||
- Adapter unit tests
|
||||
- Hook integration tests
|
||||
- Service layer tests
|
||||
- E2E tests per frontend
|
||||
|
||||
### Refactoring (Phase 5c+)
|
||||
- Update workflowui hooks
|
||||
- Update frontends/nextjs hooks
|
||||
- Add frontends/dbal support
|
||||
- Remove duplicate code
|
||||
|
||||
---
|
||||
|
||||
## File Locations
|
||||
|
||||
### Source Files to Extract
|
||||
```
|
||||
workflowui/src/
|
||||
├── hooks/useProject.ts
|
||||
├── hooks/useWorkspace.ts
|
||||
├── hooks/useWorkflow.ts
|
||||
├── hooks/useExecution.ts
|
||||
├── services/projectService.ts
|
||||
├── services/workspaceService.ts
|
||||
├── services/workflowService.ts
|
||||
└── services/executionService.ts
|
||||
|
||||
frontends/nextjs/src/
|
||||
├── hooks/useUsers.ts
|
||||
├── hooks/useUserForm.ts
|
||||
├── hooks/useUserActions.ts
|
||||
├── hooks/usePackages.ts
|
||||
├── hooks/usePackageDetails.ts
|
||||
├── hooks/usePackageActions.ts
|
||||
├── hooks/useWorkflow.ts
|
||||
└── lib/hooks/use-rest-api.ts
|
||||
|
||||
redux/slices/src/
|
||||
├── slices/projectSlice.ts
|
||||
├── slices/workspaceSlice.ts
|
||||
├── slices/workflowSlice.ts
|
||||
└── types/
|
||||
```
|
||||
|
||||
### Target Structure (Phase 5)
|
||||
```
|
||||
packages/tier2-hooks/
|
||||
├── src/adapters/
|
||||
├── src/cache/
|
||||
├── src/hooks/
|
||||
├── src/types/
|
||||
└── tests/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Full Analysis:** `docs/TIER2_HOOKS_ANALYSIS.md`
|
||||
- **Extraction Strategy:** `docs/TIER2_EXTRACTION_STRATEGY.md`
|
||||
- **Redux Architecture:** `redux/slices/README.md`
|
||||
- **Frontend Patterns:** `frontends/nextjs/src/hooks/README.md`
|
||||
|
||||
---
|
||||
|
||||
## Quick Links
|
||||
|
||||
- Analysis: `/Users/rmac/Documents/metabuilder/docs/TIER2_HOOKS_ANALYSIS.md`
|
||||
- Strategy: `/Users/rmac/Documents/metabuilder/docs/TIER2_EXTRACTION_STRATEGY.md`
|
||||
- Reference: `/Users/rmac/Documents/metabuilder/docs/TIER2_HOOKS_REFERENCE.md`
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user