mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-30 00:34:56 +00:00
johndoe6345789
28ab35ba46
Moves 45 documentation files from centralized /docs/ to subproject directories
following proximity-based organization principle. All moves use git mv to preserve history.
Changes:
- workflow/ docs: Move 27 files from docs/workflow/ to workflow/docs/
- DAG executor docs, workflow compliance, executor analysis, loaderv2 guides, etc.
- Result: workflow/docs/ now has 27 files
- dbal/ docs: Move 11 files from docs/dbal/ to dbal/docs/
- DBAL architecture, analysis, integration, and workflow integration docs
- Result: dbal/docs/ now has 18 files (11 new + 7 pre-existing)
- gameengine/ docs: Move 7 files from docs/gameengine/ to gameengine/docs/
- GameEngine compliance audits, packages, Quake3, soundboard, engine tester
- Result: gameengine/docs/ now has 20 files (7 new + 13 pre-existing)
Benefits:
- Docs are now closer to their code (easier to keep in sync)
- Reduces /docs/ clutter
- Establishes pattern for per-subproject documentation
- All git history preserved via git mv
Next phases:
- Phase 2: Move package-specific docs to /packages/{id}/docs/
- Phase 3: Separate N8N compliance docs by scope
- Phase 4: Organize UI documentation
- Phase 5: Create cross-project indices
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
174 lines
4.7 KiB
Markdown
174 lines
4.7 KiB
Markdown
# WorkflowLoaderV2 API Integration - Implementation Guide
|
|
|
|
**Status**: Phase 3 Week 4 | **Updated**: 2026-01-23 | **Scope**: 6 endpoint updates + 110 LOC
|
|
|
|
## Overview
|
|
|
|
This document guides the integration of WorkflowLoaderV2 into the Next.js workflow API endpoints. All 6 primary endpoints require updates to use the new validation layer, plugin registry, and multi-tenant safety enforcement.
|
|
|
|
---
|
|
|
|
## Task Summary
|
|
|
|
| Task | Endpoint | Changes | Status |
|
|
|------|----------|---------|--------|
|
|
| Task 8 | `GET /workflows` | Add registry validation, pagination, multi-tenant filtering | Pending |
|
|
| Task 9 | `POST /workflows` | Add creation validation with PluginValidator | Pending |
|
|
| Task 10 | `GET /workflows/:id` | Add permission check, registry lookup | Pending |
|
|
| Task 11 | `PUT /workflows/:id` | Add update validation, connection integrity check | Pending |
|
|
| Task 12 | `POST /workflows/:id/execute` | Add pre-execution validation, error recovery | Pending |
|
|
| Task 13 | `POST /workflows/validate` | New validation endpoint with full suite | Pending |
|
|
|
|
---
|
|
|
|
## Endpoint Details
|
|
|
|
### Task 8: GET /workflows - List Workflows
|
|
|
|
**Required Changes**:
|
|
1. Add `getWorkflows()` method to WorkflowService
|
|
2. Add pagination (limit, offset)
|
|
3. Add filtering (category, status)
|
|
4. Add metadata enrichment from registry
|
|
|
|
**Files to Modify**:
|
|
- `frontends/nextjs/src/app/api/v1/workflows/route.ts` (+25 lines)
|
|
- `frontends/nextjs/src/lib/workflow-service.ts` (+40 lines)
|
|
|
|
---
|
|
|
|
### Task 9: POST /workflows - Create Workflow
|
|
|
|
**Required Changes**:
|
|
1. Add PluginValidator pre-validation
|
|
2. Add node type validation from registry
|
|
3. Add connection validation
|
|
4. Add metadata auto-generation
|
|
|
|
**Files to Modify**:
|
|
- `frontends/nextjs/src/app/api/v1/workflows/route.ts` (+35 lines)
|
|
- `frontends/nextjs/src/lib/workflow-service.ts` (+45 lines)
|
|
|
|
---
|
|
|
|
### Task 10: GET /workflows/:id - Get Single Workflow
|
|
|
|
**Required Changes**:
|
|
1. Add permission check (tenant isolation)
|
|
2. Add registry lookup
|
|
3. Add error handling
|
|
4. Add validation status
|
|
|
|
**Files to Modify**:
|
|
- `frontends/nextjs/src/app/api/v1/workflows/[workflowId]/route.ts` (+30 lines)
|
|
|
|
---
|
|
|
|
### Task 11: PUT /workflows/:id - Update Workflow
|
|
|
|
**Required Changes**:
|
|
1. Add full validation before update
|
|
2. Add connection integrity check
|
|
3. Add version tracking
|
|
4. Add change auditing
|
|
|
|
**Files to Modify**:
|
|
- `frontends/nextjs/src/app/api/v1/workflows/[workflowId]/route.ts` (+50 lines)
|
|
- `frontends/nextjs/src/lib/workflow-service.ts` (+25 lines)
|
|
|
|
---
|
|
|
|
### Task 12: POST /workflows/:id/execute - Execute Workflow
|
|
|
|
**Required Changes**:
|
|
1. Add pre-execution validation
|
|
2. Add ErrorRecoveryManager integration
|
|
3. Add TenantSafetyManager enforcement
|
|
4. Add execution tracking
|
|
|
|
**Files to Modify**:
|
|
- `frontends/nextjs/src/app/api/v1/workflows/[workflowId]/execute/route.ts` (+60 lines, new)
|
|
|
|
---
|
|
|
|
### Task 13: POST /workflows/validate - New Validation Endpoint
|
|
|
|
**Required Changes**:
|
|
1. Create validation-only endpoint
|
|
2. Validate without persisting
|
|
3. Return detailed report
|
|
4. Support partial validation
|
|
|
|
**Files to Modify**:
|
|
- `frontends/nextjs/src/app/api/v1/workflows/validate/route.ts` (+55 lines, new)
|
|
|
|
---
|
|
|
|
## Files Created/Modified
|
|
|
|
| File | Change | Lines |
|
|
|------|--------|-------|
|
|
| `route.ts` (GET) | Modified | +25 |
|
|
| `route.ts` (POST) | Modified | +35 |
|
|
| `[workflowId]/route.ts` (GET) | Modified | +30 |
|
|
| `[workflowId]/route.ts` (PUT) | Modified | +50 |
|
|
| `[workflowId]/execute/route.ts` | New | +60 |
|
|
| `validate/route.ts` | New | +55 |
|
|
| `workflow-service.ts` | Modified | +110 |
|
|
|
|
**Total**: 365 new/modified lines
|
|
|
|
---
|
|
|
|
## Integration Checklist
|
|
|
|
### Task 8: List Workflows
|
|
- [ ] Update GET handler with pagination
|
|
- [ ] Add PluginRegistry enrichment
|
|
- [ ] Add filtering support
|
|
- [ ] Test multi-tenant isolation
|
|
|
|
### Task 9: Create Workflow
|
|
- [ ] Update POST handler
|
|
- [ ] Integrate PluginValidator
|
|
- [ ] Add validation error responses
|
|
- [ ] Test metadata generation
|
|
|
|
### Task 10: Get Single Workflow
|
|
- [ ] Add tenant check
|
|
- [ ] Add 404 handling
|
|
- [ ] Enrich with metadata
|
|
|
|
### Task 11: Update Workflow
|
|
- [ ] Add validation
|
|
- [ ] Implement versioning
|
|
- [ ] Add audit logging
|
|
|
|
### Task 12: Execute Workflow
|
|
- [ ] Create execute handler
|
|
- [ ] Add error recovery
|
|
- [ ] Add tenant safety
|
|
- [ ] Implement retry logic
|
|
|
|
### Task 13: Validate Workflow
|
|
- [ ] Create validate endpoint
|
|
- [ ] Add structure validation
|
|
- [ ] Add connection validation
|
|
- [ ] Return detailed report
|
|
|
|
### Final Verification
|
|
- [ ] `npm run typecheck` passes
|
|
- [ ] `npm run test` passes
|
|
- [ ] `npm run test:e2e` passes
|
|
- [ ] Multi-tenant isolation verified
|
|
- [ ] Error recovery tested
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. **Task 19-23**: DBAL workflow entity and validation adapter
|
|
2. **Task 24-30**: Comprehensive E2E testing
|
|
3. **Task 31+**: Production readiness and monitoring
|
|
|