unraid-docker-manager/.planning/phases/10.1-aggressive-workflow-modularization/10.1-02-PLAN.md

---
phase: 10.1-aggressive-workflow-modularization
plan: 02
type: execute
wave: 2
depends_on: ["10.1-01"]
files_modified:
  - n8n-workflow.json
  - n8n-batch-ui.json
autonomous: true

must_haves:
  truths:
    - "Batch selection keyboard appears when user enters batch mode"
    - "User can toggle containers on/off in batch selection"
    - "User can navigate pagination in batch selection"
    - "User can execute batch actions (stop/restart/update)"
    - "Batch summary shows results after execution"
  artifacts:
    - path: "n8n-batch-ui.json"
      provides: "Batch UI orchestration sub-workflow"
      contains: "Execute Workflow Trigger"
    - path: "n8n-workflow.json"
      provides: "Main workflow with batch UI extraction"
  key_links:
    - from: "n8n-workflow.json"
      to: "n8n-batch-ui.json"
      via: "Execute Workflow node"
      pattern: "executeWorkflow.*batch"
    - from: "n8n-batch-ui.json"
      to: "n8n-actions.json"
      via: "Execute Workflow node for batch actions"
      pattern: "executeWorkflow"
    - from: "n8n-batch-ui.json"
      to: "n8n-update.json"
      via: "Execute Workflow node for batch updates"
      pattern: "executeWorkflow"
---

<objective>
Extract batch UI nodes from main workflow into dedicated n8n-batch-ui.json sub-workflow.

Purpose: Remove ~40-50 nodes from main workflow by extracting the cohesive batch selection/navigation/execution domain.
Output: New n8n-batch-ui.json sub-workflow, updated main workflow with batch nodes extracted.
</objective>

<execution_context>
@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
@/home/luc/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/10.1-aggressive-workflow-modularization/10.1-CONTEXT.md
@.planning/phases/10.1-aggressive-workflow-modularization/10.1-01-SUMMARY.md
@n8n-workflow.json
@n8n-actions.json
@n8n-update.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create n8n-batch-ui.json sub-workflow with extracted batch nodes</name>
  <files>n8n-batch-ui.json (new)</files>
  <action>
Create new sub-workflow containing all batch UI related nodes from main workflow.

**Input contract (Execute Workflow Trigger):**
- chatId: number (required)
- messageId: number (optional, 0 for new message)
- callbackData: string (the callback data triggering batch action)
- responseMode: string ('text' or 'callback')

**Nodes to extract** (all nodes with "Batch" in name + related batch state nodes):
- Build Batch Keyboard, Build Batch Select Keyboard, Edit Batch Select Keyboard, Edit To Batch Select Keyboard
- Rebuild Batch Select Keyboard, Send Batch Confirmation, Send Batch Start Message, Send Batch Summary
- Build Batch Select Stop Confirmation, Build Batch Stop Confirmation, Build Batch Stop Expired
- Check Batch Stop Expired, Send Batch Stop Confirmation, Send Batch Stop Expired, Delete Batch Confirm Message
- Delete Batch Select Message, Delete Batch Stop Cancel Message
- Handle Batch Toggle, Handle Batch Clear, Handle Batch Exec, Handle Batch Action Result Sub
- Handle Batch Update Result, Execute Batch Action Sub-workflow, Execute Batch Update
- Initialize Batch State, Is Batch Command, Is Batch Complete, Match Batch Containers
- Needs Batch Confirmation, Prepare Batch Action Input, Prepare Batch Cancel Return
- Prepare Batch Exec, Prepare Batch Loop, Prepare Batch Nav, Prepare Batch Stop Exec
- Prepare Batch Update Input, Prepare Immediate Batch Exec, Prepare Update All Batch
- Route Batch Action, Route Batch Loop Action, Detect Batch Command, Get Containers for Batch
- Fetch Containers For Batch Mode, Answer Batch* nodes (all Answer Batch callbacks)

**Structure:**
1. Execute Workflow Trigger (entry point)
2. Parse Input (validate and extract callback data)
3. Route Batch Action (switch on callback type: toggle, clear, exec, nav, cancel)
4. Domain logic for each branch
5. Return structured result to main workflow

**Output contract (return to main workflow):**
```javascript
{
  success: true/false,
  action: 'toggle|clear|exec|nav|cancel|summary',
  // For keyboard updates:
  keyboard: {...} || null,
  text: "message text",
  // For execution results:
  results: [{containerId, containerName, success, message}],
  // Error info:
  error: "error message" || null
}
```

**Important:** Sub-workflow should call existing single-container sub-workflows (n8n-actions.json, n8n-update.json) for actual container operations in batch loops.
  </action>
  <verify>
- `cat n8n-batch-ui.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'Nodes: {len(d.get(\"nodes\",[]))}')"` shows node count
- Sub-workflow has Execute Workflow Trigger node
- Sub-workflow has Execute Workflow nodes calling n8n-actions.json and n8n-update.json
  </verify>
  <done>n8n-batch-ui.json created with all batch UI nodes extracted from main workflow structure.</done>
</task>

<task type="auto">
  <name>Task 2: Update main workflow to call batch UI sub-workflow</name>
  <files>n8n-workflow.json</files>
  <action>
Modify main workflow to replace batch nodes with Execute Workflow call to n8n-batch-ui.json.

1. **Remove extracted batch nodes** from main workflow (all nodes identified in Task 1)

2. **Add Execute Workflow node** ("Execute Batch UI"):
   - Source: database
   - WorkflowId: use TODO_DEPLOY_BATCH_UI_WORKFLOW placeholder (same pattern as logs)
   - Mode: once
   - waitForSubWorkflow: true
   - Input: { chatId, messageId, callbackData, responseMode }

3. **Update routing** in main workflow:
   - Route Callback should route batch callbacks (bsel:, bexec:, bnav:, bclear:, bcancel:) to new Execute Batch UI node
   - Handle result from sub-workflow (success/failure, keyboard updates, error messages)

4. **Add result handler** after Execute Batch UI:
   - If result has keyboard: send/edit Telegram message with keyboard
   - If result has error: send error message
   - If result has summary: send summary message

5. **Preserve Answer Callback nodes** in main workflow for the batch callbacks, OR move them to sub-workflow if they're tightly coupled with batch logic.

**Data flow:**
Main receives callback -> Route Callback -> Execute Batch UI sub-workflow -> Return result -> Send Telegram response

**Verification after changes:**
- Count nodes in main workflow (should be ~140-150 after this extraction)
- Verify Route Callback still has proper branches
  </action>
  <verify>
- `cat n8n-workflow.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'Main workflow nodes: {len(d.get(\"nodes\",[]))}')"` shows reduced count (~140-150)
- Main workflow has "Execute Batch UI" node
- No batch-related nodes remain in main workflow except routing entry point
- TODO_DEPLOY_BATCH_UI_WORKFLOW placeholder is searchable
  </verify>
  <done>Main workflow updated with batch nodes extracted and replaced by sub-workflow call.</done>
</task>

<task type="auto">
  <name>Task 3: Create backup and commit extraction</name>
  <files>n8n-workflow.json.backup-batch</files>
  <action>
1. Create explicit backup before committing (per CONTEXT.md rollback strategy):
   `cp n8n-workflow.json n8n-workflow.json.backup-batch`

2. Verify the extraction is complete:
   - Main workflow node count reduced by ~40-50
   - n8n-batch-ui.json exists with extracted nodes
   - No orphan references in main workflow

3. Commit the extraction:
   ```bash
   git add n8n-workflow.json n8n-batch-ui.json n8n-workflow.json.backup-batch
   git commit -m "feat(10.1-02): extract batch UI to sub-workflow

   - Created n8n-batch-ui.json with ~45 batch-related nodes
   - Main workflow reduced from 192 to ~145 nodes
   - Batch UI sub-workflow calls n8n-actions.json and n8n-update.json for operations
   - Added TODO_DEPLOY_BATCH_UI_WORKFLOW placeholder for n8n import"
   ```
  </action>
  <verify>
- Backup file exists: `ls n8n-workflow.json.backup-batch`
- Git commit created with extraction changes
- `git log -1` shows commit message about batch extraction
  </verify>
  <done>Batch UI extraction committed with backup file for rollback if needed.</done>
</task>

</tasks>

<verification>
- [ ] n8n-batch-ui.json exists with Execute Workflow Trigger
- [ ] Main workflow node count reduced by ~40-50 nodes
- [ ] Main workflow has Execute Batch UI node with TODO placeholder
- [ ] Backup file created before commit
- [ ] Git commit records the extraction
</verification>

<success_criteria>
1. New n8n-batch-ui.json sub-workflow created with all batch UI logic
2. Main workflow reduced from 192 to ~140-150 nodes
3. Sub-workflow properly calls existing action/update sub-workflows
4. Backup created for rollback capability
5. Changes committed to git
</success_criteria>

<output>
After completion, create `.planning/phases/10.1-aggressive-workflow-modularization/10.1-02-SUMMARY.md`
</output>