Lucas Berger
1ef726942a
Research found Unraid badge issue is architectural (bot bypasses Unraid's XML template system). Updated plans to document limitation with workaround instead of attempting programmatic fix. Plan 01 covers docs/env/debt, Plan 02 covers deferred Update All UAT. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
189 lines
7.9 KiB
Markdown
189 lines
7.9 KiB
Markdown
# Roadmap — Unraid Docker Manager
|
|
|
|
## Milestones
|
|
|
|
- **v1.0 Docker Control via Telegram** — Phases 1-5 (shipped 2026-02-02) -> [Archive](milestones/v1.0-ROADMAP.md)
|
|
- **v1.1 n8n Integration & Polish** — Phases 6-9 (shipped 2026-02-04) -> [Archive](milestones/v1.1-ROADMAP.md)
|
|
- **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:
|
|
- [x] 10-01-PLAN.md — Orphan node cleanup (removed 2 orphan nodes)
|
|
- [x] 10-02-PLAN.md — Extract container update sub-workflow (consolidates DEBT-03)
|
|
- [x] 10-03-PLAN.md — Extract container actions sub-workflow (start/stop/restart)
|
|
- [x] 10-04-PLAN.md — Integration verification and user checkpoint
|
|
- [x] 10-05-PLAN.md — Complete modularization (batch operations, logs sub-workflow)
|
|
- [x] 10-06-PLAN.md — Remediation: fix routing gaps, wire logs, cleanup Python scripts
|
|
- [x] 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:** 9 plans
|
|
|
|
Plans:
|
|
- [x] 10.1-01-PLAN.md — Rename sub-workflows, analyze domain boundaries, get user approval
|
|
- [x] 10.1-02-PLAN.md — Extract Batch UI sub-workflow (~50 nodes)
|
|
- [x] 10.1-03-PLAN.md — Extract Container Status sub-workflow (~10-15 nodes)
|
|
- [x] 10.1-04-PLAN.md — Extract Confirmation sub-workflow (~15-20 nodes)
|
|
- [x] 10.1-05-PLAN.md — Integration verification and UAT
|
|
- [x] 10.1-06-PLAN.md — Gap closure: Extract Matching/Disambiguation sub-workflow
|
|
- [x] 10.1-07-PLAN.md — Gap closure: Code node classification + contract documentation
|
|
- [x] 10.1-08-PLAN.md — UAT gap closure: Fix action result statusCode handling (n8n-actions.json)
|
|
- [x] 10.1-09-PLAN.md — UAT gap closure: Fix batch keyboard, cancel routing, /list command (n8n-workflow.json)
|
|
|
|
**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)
|
|
6. All sub-workflows have clean input/output contracts
|
|
|
|
---
|
|
|
|
### Phase 10.2: Better Logging and Log Management (INSERTED)
|
|
|
|
**Goal:** Add correlation ID tracking for request tracing across sub-workflow boundaries
|
|
|
|
**Dependencies:** Phase 10.1 (aggressive modularization complete)
|
|
|
|
**Requirements:** LOG-01 (error ring buffer), LOG-02 (sub-workflow error propagation), LOG-03 (debug commands), LOG-04 (debug mode tracing)
|
|
|
|
**Plans:** 4 plans
|
|
|
|
Plans:
|
|
- [x] 10.2-01-PLAN.md -- Error ring buffer foundation + hidden Telegram debug commands
|
|
- [x] 10.2-02-PLAN.md -- Sub-workflow error propagation + correlation ID tracking
|
|
- [x] 10.2-03-PLAN.md -- Debug mode tracing + deployment verification
|
|
- [x] 10.2-04-PLAN.md -- UAT gap closure: wire correlation ID generators and remove orphan nodes
|
|
|
|
**Success Criteria:** (descoped — n8n static data does not persist between executions)
|
|
1. ~~Errors from sub-workflow failures automatically captured in ring buffer~~ (removed — platform limitation)
|
|
2. ~~/errors, /clear-errors, /debug, /trace hidden commands~~ (removed — platform limitation)
|
|
3. ✓ Correlation IDs trace single user requests across main + sub-workflow boundaries
|
|
4. ~~Debug mode captures sub-workflow I/O boundary data~~ (removed — platform limitation)
|
|
5. ✓ No regression to existing bot functionality after deployment
|
|
6. ✓ All 7 sub-workflows return structured error objects (success/false + error details)
|
|
|
|
**Note:** n8n workflow static data is execution-scoped, not workflow-scoped. Ring buffer architecture not viable. Retained: correlation IDs, structured error returns, correlationId pass-through.
|
|
|
|
---
|
|
|
|
### 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:** 2 plans
|
|
|
|
Plans:
|
|
- [x] 11-01-PLAN.md — Bitmap-encoded batch selection (replaces CSV-in-callback to eliminate 64-byte limit)
|
|
- [x] 11-02-PLAN.md — Update All inline keyboard button, deployment, and UAT verification
|
|
|
|
**Success Criteria:**
|
|
1. ○ User can type "update all" to update all :latest containers with confirmation (code deployed, UAT deferred to Phase 12)
|
|
2. ○ User can tap "Update All" in inline keyboard to update all :latest containers (code deployed, UAT deferred to Phase 12)
|
|
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:** 2 plans
|
|
|
|
Plans:
|
|
- [ ] 12-01-PLAN.md — Documentation update (README, env vars, DEBT-02 verification) + Unraid badge investigation
|
|
- [ ] 12-02-PLAN.md — Deferred UAT: Update All text command (BATCH-04) and inline keyboard (BATCH-05)
|
|
|
|
**Success Criteria:**
|
|
1. Unraid update badge behavior documented as known limitation with workaround (bot bypasses Unraid template system)
|
|
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 | Complete |
|
|
| 10.2 | Better Logging & Log Management | v1.2 | Complete (descoped) |
|
|
| 11 | Update All & Callback Limits | v1.2 | Complete (UAT partial, 2 deferred) |
|
|
| 12 | Polish & Audit | v1.2 | Planned |
|
|
| 13 | Documentation Overhaul | v1.2 | Pending |
|
|
|
|
**v1.2 Coverage:** 12+ requirements mapped across 7 phases
|
|
|
|
---
|
|
*Updated: 2026-02-08 — Phase 12 planned (2 plans in 1 wave)*
|