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

Roadmap — Unraid Docker Manager

Milestones

• v1.0 Docker Control via Telegram — Phases 1-5 (shipped 2026-02-02) -> Archive
• v1.1 n8n Integration & Polish — Phases 6-9 (shipped 2026-02-04) -> Archive
• v1.2 Modularization & Polish — Phases 10-13 + 10.1, 10.2 (planned)

---

v1.2: Modularization & Polish

Modularize the workflow for maintainability, add "update all" functionality, fix callback data limits, and polish remaining issues.

Phase 10: Workflow Modularization

Goal: Break main workflow into modular sub-workflows for maintainability

Dependencies: None

Requirements: MOD-01, MOD-02, DEBT-03

Plans: 7 plans

Plans:

• 10-01-PLAN.md — Orphan node cleanup (removed 2 orphan nodes)
• 10-02-PLAN.md — Extract container update sub-workflow (consolidates DEBT-03)
• 10-03-PLAN.md — Extract container actions sub-workflow (start/stop/restart)
• 10-04-PLAN.md — Integration verification and user checkpoint
• 10-05-PLAN.md — Complete modularization (batch operations, logs sub-workflow)
• 10-06-PLAN.md — Remediation: fix routing gaps, wire logs, cleanup Python scripts
• 10-07-PLAN.md — UAT gap closure: race conditions, data chains, fuzzy matching, error handling

Success Criteria:

1. ✓ Workflow split into logical sub-workflows (update, actions, logs)
2. ✓ Sub-workflows callable from main without code duplication
3. ✓ Update flow consolidated between single and batch paths
4. ✓ Actions flow consolidated between single and batch paths
5. ✓ Main workflow reduced from 209 to 192 nodes (-8%)
6. ✓ All existing functionality still works after modularization

Note: Deeper modularization (target 120-140 nodes) deferred to Phase 10.1

---

Phase 10.1: Aggressive Workflow Modularization (INSERTED)

Goal: Decompose main workflow to minimal trigger/auth/routing (~50-80 nodes) with domain sub-workflows

Dependencies: Phase 10 (initial modularization complete)

Requirements: MOD-03 (new)

Plans: 6 plans

Plans:

• 10.1-01-PLAN.md — Rename sub-workflows, analyze domain boundaries, get user approval
• 10.1-02-PLAN.md — Extract Batch UI sub-workflow (~50 nodes)
• 10.1-03-PLAN.md — Extract Container Status sub-workflow (~10-15 nodes)
• 10.1-04-PLAN.md — Extract Confirmation sub-workflow (~15-20 nodes)
• 10.1-05-PLAN.md — Integration verification and UAT
• 10.1-06-PLAN.md — Gap closure: document contracts, analyze Code nodes, decide on remaining gaps

Success Criteria:

1. Main workflow contains only: trigger, auth, keyword routing, sub-workflow dispatch
2. UX/Keyboard sub-workflow handles all batch selection UI and pagination
3. Container Status sub-workflow handles list and status display
4. Confirmation sub-workflow handles all confirmation dialogs
5. Main workflow reduced to ~50-80 nodes (from 192) — Revised: 115-125 realistic target
6. All sub-workflows have clean input/output contracts

Note: Original 50-80 target was unrealistic (58 Telegram response nodes locked to main). Revised target 115-125. Current: 168 nodes after 3 domain extractions. Gap closure plan addresses remaining verification gaps.

---

Phase 10.2: Better Logging and Log Management (INSERTED)

Goal: Improve logging capabilities and log management features

Dependencies: Phase 10.1 (aggressive modularization complete)

Requirements: TBD

Plans: 0 plans

Plans:

• TBD (run /gsd:plan-phase 10.2 to break down)

Success Criteria:

1. [To be defined during planning]

---

Phase 11: Update All & Callback Limits

Goal: Add "update all" functionality and fix callback data limits for batch selection

Dependencies: Phase 10 (modularization provides cleaner base for new features)

Requirements: BATCH-04, BATCH-05, BATCH-06, BATCH-07

Plans: 0 plans

Plans:

• TBD (run /gsd:plan-phase 11 to break down)

Success Criteria:

1. User can type "update all" to update all :latest containers with confirmation
2. User can tap "Update All" in inline keyboard to update all :latest containers
3. Batch selection keyboard allows selecting 5+ containers without hitting callback limit
4. Containers with long names (20+ chars) can be selected in batch keyboard

---

Phase 12: Polish & Audit

Goal: Clear Unraid update badges, verify environment configuration, and fix remaining tech debt

Dependencies: Phase 11 (features complete before polish)

Requirements: UNR-01, ENV-01, ENV-02, DEBT-02

Plans: 0 plans

Plans:

• TBD (run /gsd:plan-phase 12 to break down)

Success Criteria:

1. After bot successfully updates a container, Unraid UI no longer shows "update available" for that container
2. Documentation clarifies whether TELEGRAM_USERID env var is required or can be hardcoded
3. Documentation clarifies whether TELEGRAM_BOT_TOKEN env var is required or if n8n credential suffices
4. Image pull command has single --max-time flag (600s)

---

Phase 13: Documentation Overhaul

Goal: Update README and documentation to reflect current architecture and features

Dependencies: Phase 12 (core features complete before documentation)

Requirements: DEBT-01

Plans: 0 plans

Plans:

• TBD (run /gsd:plan-phase 13 to break down)

Success Criteria:

1. README documents docker-socket-proxy architecture (not direct socket mount)
2. README documents all v1.2 features (update all, batch selection improvements)
3. Setup instructions verified accurate for clean install

---

Progress

Phase	Name	Milestone	Status
1-5	Foundation through Polish	v1.0	Complete
6	n8n API Access	v1.1	Complete
7	Socket Security	v1.1	Complete
8	Inline Keyboard Infrastructure	v1.1	Complete
9	Batch Operations	v1.1	Complete
10	Workflow Modularization	v1.2	Complete
10.1	Aggressive Workflow Modularization	v1.2	Gap Closure
10.2	Better Logging & Log Management	v1.2	Pending (INSERTED)
11	Update All & Callback Limits	v1.2	Pending
12	Polish & Audit	v1.2	Pending
13	Documentation Overhaul	v1.2	Pending

v1.2 Coverage: 12+ requirements mapped across 7 phases

---

Updated: 2026-02-05 — Phase 10.1 gap closure plan added (10.1-06)