luckberg/unraid-docker-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
403ac53b90c8a60f33a533209b7cbc85f5a8b7c4
unraid-docker-manager/.planning/phases/10.1-aggressive-workflow-modularization/10.1-06-SUMMARY.md
T
Lucas Berger 4eeed1d9e1 docs(10.1-06): complete matching extraction plan
2026-02-08 18:56:44 -05:00

6.4 KiB
Raw Blame History

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, duration, completed
phase plan subsystem tags requires provides affects tech-stack key-files key-decisions patterns-established duration completed
10.1-aggressive-workflow-modularization 06 workflow
n8n
sub-workflow
matching
disambiguation
fuzzy-matching
phase provides
10.1-01 Domain analysis identifying matching/disambiguation as 4th extractable domain
phase provides
10.1-04 Main workflow at 168 nodes baseline
n8n-matching.json sub-workflow (23 nodes)
Matching/disambiguation domain extracted from main workflow
All 4 viable domains now extracted
10.1-07
deployment
added patterns
Action-based sub-workflow return pattern for matching results
Prepare Execution node to transform sub-workflow output to downstream format
created modified
n8n-matching.json
n8n-workflow.json.backup-matching
n8n-workflow.json
DEPLOY-SUBWORKFLOWS.md
Matching sub-workflow returns action field but not the user's requested action (stop/start/etc) — downstream nodes read action from Parse Action Command or Detect Batch Command directly
Text-mode status needs keyboard stripped — added Strip Status Keyboard node
Batch text commands need data transformation — added Prepare Batch Execution node to map matchedContainers to allMatched
When sub-workflow replaces inline logic, downstream nodes may need to reference original data sources (e.g., Parse Action Command) instead of sub-workflow output for fields not passed through
Text vs callback mode routing via messageId check (Has Status Message ID pattern)
16min 2026-02-08

Phase 10.1 Plan 06: Matching/Disambiguation Sub-workflow Summary

Extracted matching/disambiguation domain into n8n-matching.json sub-workflow (23 nodes), deployed via API, fixed 3 data flow issues found during runtime verification

Performance

  • Duration: ~16 min
  • Started: 2026-02-08T13:30:00Z
  • Completed: 2026-02-08T14:05:26Z
  • Tasks: 3 (2 auto + 1 checkpoint)
  • Files modified: 3

Accomplishments

  • Created n8n-matching.json sub-workflow with 23 nodes (12 logic + 1 trigger + 1 router + 9 format-return)
  • Three matching paths: action match, update match, batch match
  • Deployed via n8n API (ID: kL4BoI8ITSP9Oxek)
  • All 6 Telegram response nodes preserved in main workflow per locked decision
  • Fixed pre-existing text-mode status routing bug (editMessageText with messageId 0)
  • Main workflow: 168 nodes (net 0 change due to fix nodes added during verification)

Task Commits

Each task was committed atomically:

  1. Task 1: Create n8n-matching.json - e86941c (feat)
  2. Task 2: Update main workflow - de64d1b (feat)
  3. Task 3: Deploy and verify - fc955e6 (fix: deploy IDs), 22638fd (fix: action passthrough + status routing), 11365b8 (fix: strip status keyboard), cccf455 (fix: batch data flow)

Files Created/Modified

  • n8n-matching.json - New sub-workflow: fuzzy container matching, disambiguation, suggestion building (23 nodes)
  • n8n-workflow.json - Main workflow with matching extracted and integration fixes (168 nodes)
  • n8n-workflow.json.backup-matching - Pre-extraction backup

Decisions Made

  1. Action passthrough pattern: The matching sub-workflow doesn't carry the user's requested action (stop/start/restart) through its return data. Downstream nodes reference the original parse node (Parse Action Command or Detect Batch Command) directly for the action type. This avoids expanding the sub-workflow's input/output contract.

  2. Text-mode status routing: Added Has Status Message ID If node to route status_direct results — messageId > 0 goes to Edit Container List (callback), messageId == 0 goes to text send via Strip Status Keyboard → Send Container Submenu Direct.

  3. Batch data transformation: Added Prepare Batch Execution Code node to map matchedContainers → allMatched and inject the real batch action from Detect Batch Command, since downstream nodes expect different field names than the sub-workflow returns.

Deviations from Plan

Auto-fixed Issues

1. [Rule 1 - Bug] Action type not passed through matching sub-workflow

  • Found during: Task 3 (runtime verification)
  • Issue: Prepare Text Action Input read data.actionType which resolved to "action" (a routing label) instead of "stop"
  • Fix: Changed to read $('Parse Action Command').item.json.action directly
  • Files modified: n8n-workflow.json
  • Verification: "stop booklore" correctly executes stop
  • Committed in: 22638fd

2. [Rule 1 - Bug] Text-mode status sent to editMessageText with messageId 0

  • Found during: Task 3 (runtime verification)
  • Issue: Pre-existing bug — "status book" routed to Edit Container List (editMessageText) which fails with messageId 0. Also showed inline keyboard buttons for text commands.
  • Fix: Added Has Status Message ID If node and Strip Status Keyboard Code node for text-mode routing
  • Files modified: n8n-workflow.json
  • Verification: "status book" sends plain text without buttons
  • Committed in: 22638fd, 11365b8

3. [Rule 1 - Bug] Batch text commands: wrong field names and action

  • Found during: Task 3 (runtime verification)
  • Issue: Downstream nodes expected allMatched but sub-workflow returned matchedContainers. Route Batch Action got action: "batch_matched" instead of "stop".
  • Fix: Added Prepare Batch Execution Code node to transform data
  • Files modified: n8n-workflow.json
  • Verification: "stop plex dup" correctly executes batch stop
  • Committed in: cccf455

Total deviations: 3 auto-fixed (3 bugs) Impact on plan: All bugs were data flow mismatches caused by the sub-workflow returning different field names/values than what downstream nodes expected. The matching logic itself worked correctly. Node count is 168 instead of planned 165 due to 3 additional fix nodes (Has Status Message ID, Strip Status Keyboard, Prepare Batch Execution).

Issues Encountered

None beyond the deviations above — all resolved during runtime verification.

User Setup Required

None — deployed via n8n API during execution.

Next Phase Readiness

  • Matching sub-workflow created and deployed (7th sub-workflow)
  • All 4 viable extraction domains complete
  • Ready for plan 10.1-07: Code node classification and contract documentation

Phase: 10.1-aggressive-workflow-modularization Completed: 2026-02-08

Reference in New Issue View Git Blame Copy Permalink