unraid-docker-manager/.planning/STATE.md

Project State — Unraid Docker Manager

Current Position

• Milestone: v1.2 — Modularization & Polish
• Phase: 10.1 of 13 (Aggressive Workflow Modularization)
• Plan: 6 of 7 complete (plan 07 remaining: documentation)
• Status: Gap closure in progress
• Last activity: 2026-02-08 — Completed 10.1-06 matching extraction + deployment

Progress

v1.0: [██████████] 100% SHIPPED
v1.1: [██████████] 100% SHIPPED

v1.2: [███████░░░] 65%

Phase 10:   Workflow Modularization         [██████████] 100% COMPLETE (+ 10-07 UAT fixes)
Phase 10.1: Aggressive Modularization       [████████░░] 86% Gap Closure (6/7 plans)
Phase 10.2: Better Logging & Log Management [          ] Pending (INSERTED)
Phase 11:   Update All & Callback Limits    [          ] Pending
Phase 12:   Polish & Audit                  [          ] Pending
Phase 13:   Documentation Overhaul          [          ] Pending

Phase 10 Completion Summary

Plan	Description	Status
10-01	Orphan node cleanup	Complete
10-02	Container Update sub-workflow	Complete
10-03	Container Actions sub-workflow	Complete
10-04	Integration verification	Complete
10-05	Complete modularization (batch, logs)	Complete
10-06	Remediation: routing, logs, cleanup	Complete
10-07	UAT gap closure (5 fixes)	Complete

Achievements:

• 3 sub-workflows created and deployed (Update, Actions, Logs)
• All container operations consolidated (no duplicate logic)
• Old inline batch execution path removed
• Legacy callbacks modernized to new format
• Main workflow: 209 -> 192 nodes (-8%)
• 6 Python helper scripts removed
• UAT gaps closed: race condition, data chain errors, fuzzy matching, refresh errors

Key Artifacts

• n8n-workflow.json — Main workflow (168 nodes, down from 178)
• n8n-batch-ui.json — Batch UI sub-workflow (16 nodes) — Deployed
• n8n-status.json — Container Status sub-workflow (11 nodes) — ID: lqpg2CqesnKE2RJQ
• n8n-confirmation.json — Confirmation Dialogs sub-workflow (16 nodes) — Deployed
• n8n-update.json — ID: 7AvTzLtKXM2hZTio92_mC
• n8n-actions.json — ID: fYSZS5PkH0VSEaT5
• n8n-logs.json — ID: oE7aO2GhbksXDEIw

Technical Notes

n8n typeVersion 1.2 requirement:

"workflowId": { "__rl": true, "mode": "list", "value": "<id>" }

Docker API success detection:

• 204 No Content = success (empty response body)
• Check !response.message && !response.error

Sub-workflow input contracts:

• Container Update: containerId, containerName, chatId, messageId, responseMode
• Container Actions: containerId, containerName, action, chatId, messageId, responseMode
• Container Logs: containerId/containerName, lineCount, chatId, messageId, responseMode
• Batch UI: chatId, messageId, queryId, callbackData, action, batchPage, selectedCsv, toggleName
• Container Status: chatId, messageId, action, containerId, containerName, page, queryId, searchTerm
• Confirmation: chatId, messageId, action, containerId, containerName, confirmAction, confirmationToken, expired, responseMode

Sub-workflow output patterns:

• Batch UI returns action field (keyboard/confirmation/execute/cancel/limit_reached)
• Container Status returns action field (list/status/paginate/status_direct)
• Confirmation returns action field (show_stop/show_update/confirm_stop_result/confirm_update/cancel/expired)
• Main workflow routes based on action to appropriate Telegram response handler

Data chain pattern (10-07):

• Use $('Build Progress Message').item.json to reference data across async nodes
• Do not rely on $json after Telegram API calls (response overwrites data)

Accumulated Decisions

Phase	Decision	Rationale
10-05	Use placeholder workflow ID for logs sub-workflow	ID assigned by n8n on import
10-05	Retain Parse Logs Command in main workflow	Handles error cases before sub-workflow call
10-06	Remove old batch inline path	Migrated to bexec: callback format, uses sub-workflow
10-06	Defer aggressive modularization to 10.1	Core goals achieved, deeper work needs separate phase
10-07	Timestamp on logs refresh	Prevents "message not modified" error, shows freshness
10-07	Fuzzy matching in logs sub-workflow	Simpler than duplicating Docker query infrastructure
10.1-01	Realistic target 115-125 nodes (not 50-80)	58 Telegram response nodes locked to main workflow
10.1-01	Wave 2: Batch UI + Container List extraction	Highest-value domains with clear boundaries
10.1-02	Partial batch UI extraction (UI only, not loop)	Batch execution loop cannot be in sub-workflow due to n8n limitations
10.1-02	Action-based sub-workflow routing	Sub-workflow returns action field, main routes to Telegram handlers
10.1-03	Minimal net node reduction due to integration overhead	Removed 10 nodes but added 9 integration nodes; value is complexity reduction
10.1-04	Return confirm_update action to main workflow	Update flow tightly integrated with existing update sub-workflow
10.1-04	Call n8n-actions.json for stop execution	Reuse existing action execution instead of duplicating Docker API calls
10.1-06	Downstream nodes reference original parse nodes for action type	Sub-workflow doesn't carry user's requested action (stop/start) through return data
10.1-06	Text-mode status needs keyboard strip + messageId routing	Pre-existing bug exposed by testing; text commands have no message to edit
10.1-06	Batch text needs Prepare Batch Execution transform	Sub-workflow returns matchedContainers/batch_matched, downstream expects allMatched/stop

Phase 10.1 Progress

Plan	Description	Status
10.1-01	Foundation and Domain Analysis	Complete
10.1-02	Batch UI Sub-workflow (Wave 2)	Complete
10.1-03	Container Status Sub-workflow (Wave 2)	Complete
10.1-04	Confirmation Sub-workflow (Wave 3)	Complete
10.1-05	Integration Verification	Complete
10.1-06	Matching Sub-workflow Extraction	Complete

Node count progress:

• Start: 192 nodes
• After 10.1-02: 179 nodes (-13)
• After 10.1-03: 178 nodes (-1)
• After 10.1-04: 168 nodes (-10)
• After 10.1-06: 168 nodes (net 0: -12 extracted, +9 integration, +3 fix nodes)
• Target: 115-125 nodes

Extraction complete:

• Batch UI: -13 nodes (16 nodes in sub-workflow)
• Container Status: -1 net (11 nodes in sub-workflow, complexity reduction)
• Confirmation: -10 nodes (16 nodes in sub-workflow)
• Matching: net 0 (23 nodes in sub-workflow, complexity reduction)
• Total reduction: 24 nodes (192 -> 168)

Phase 10.1 Sub-workflows

All 7 sub-workflows deployed and operational:

• n8n-update.json — 7AvTzLtKXM2hZTio92_mC
• n8n-actions.json — fYSZS5PkH0VSEaT5
• n8n-logs.json — oE7aO2GhbksXDEIw
• n8n-batch-ui.json — ZJhnGzJT26UUmW45
• n8n-status.json — lqpg2CqesnKE2RJQ
• n8n-confirmation.json — fZ1hu8eiovkCk08G
• n8n-matching.json — kL4BoI8ITSP9Oxek

Next Step

Execute plan 10.1-07 (Code node classification + contract documentation).

Session Continuity

Last session: 2026-02-08 Stopped at: Completed 10.1-06, executing 10.1-07 next Resume file: None

---

Auto-maintained by GSD workflow