# Requirements: Unraid Docker Manager

**Defined:** 2026-02-09
**Core Value:** When you get a container update notification or notice a service is down, you can immediately investigate and act from your phone.

## v1.4 Requirements

Requirements for v1.4 Unraid API Native milestone. Each maps to roadmap phases.

### API Migration

- [ ] **API-01**: Container status query works via Unraid GraphQL API (replaces Docker REST API)
- [ ] **API-02**: Container start works via Unraid GraphQL mutation
- [ ] **API-03**: Container stop works via Unraid GraphQL mutation
- [ ] **API-04**: Container restart works via sequential stop+start GraphQL mutations (no native restart)
- [ ] **API-05**: Container update works via single `updateContainer` GraphQL mutation (replaces 5-step Docker flow)
- [ ] **API-06**: Batch container update works via `updateContainers` GraphQL mutation
- [ ] **API-07**: "Update all :latest" works via Unraid GraphQL API with :latest filtering
- [ ] **API-08**: Unraid update badges clear automatically after bot-initiated updates (no manual sync)

### Infrastructure

- [ ] **INFRA-01**: Container ID translation layer maps names to Unraid PrefixedID format (129-char `server_hash:container_hash`)
- [ ] **INFRA-02**: Callback data encoding works with Unraid PrefixedIDs within Telegram's 64-byte limit
- [ ] **INFRA-03**: GraphQL response normalization transforms Unraid API responses to match workflow contracts
- [ ] **INFRA-04**: GraphQL error handling standardized (check `response.errors[]`, handle HTTP 304 "already in state")
- [ ] **INFRA-05**: Timeout configuration accounts for myunraid.net cloud relay latency (200-500ms per request)

### Cleanup

- [ ] **CLN-01**: Docker socket proxy references removed from all workflow JSON files
- [ ] **CLN-02**: Container logs feature removed from workflows (text command, inline keyboard, sub-workflow)
- [ ] **CLN-03**: n8n-logs.json sub-workflow removed or emptied
- [ ] **CLN-04**: docker-socket-proxy container can be safely removed (no remaining dependencies)
- [ ] **CLN-05**: n8n container config cleaned (remove proxy network, socket-related env vars)
- [ ] **CLN-06**: "unraid" test command updated or removed (v1.3 connectivity test)

### Documentation

- [ ] **DOC-01**: README.md updated to reflect Unraid API-native architecture (remove proxy references)
- [ ] **DOC-02**: ARCHITECTURE.md updated with Unraid GraphQL API contracts and patterns
- [ ] **DOC-03**: CLAUDE.md updated with new API patterns and removed proxy recipes
- [ ] **DOC-04**: Cleanup instructions documented for removing docker-socket-proxy container

## Future Requirements

Deferred to future release. Tracked but not in current roadmap.

### Container Logs (Removed in v1.4)

- **LOGS-01**: Container logs via Unraid GraphQL API (if API adds logs support in future)
- **LOGS-02**: Container logs via SSH fallback (alternative to Docker socket proxy)

### Advanced Features

- **ADV-01**: Real-time container stats via GraphQL subscription
- **ADV-02**: Container autostart configuration via bot
- **ADV-03**: Port conflict detection and reporting
- **ADV-04**: Direct LAN fallback if myunraid.net relay unavailable

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| Container logs via Telegram | Removed in v1.4 — not valuable enough to justify hybrid architecture (Docker proxy + Unraid API) |
| GraphQL subscriptions (WebSocket) | Requires infrastructure n8n doesn't natively support, high complexity for low value |
| Dual API support (Docker + Unraid) | No hybrid architecture — single API simplifies maintenance and debugging |
| New container deployment | Manage existing only, deployment rarely needed from mobile |
| Natural language understanding | Simple keyword matching works, Claude API adds unnecessary complexity |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| INFRA-01 | Phase 15 | Pending |
| INFRA-02 | Phase 15 | Pending |
| INFRA-03 | Phase 15 | Pending |
| INFRA-04 | Phase 15 | Pending |
| INFRA-05 | Phase 15 | Pending |
| API-01 | Phase 16 | Pending |
| API-02 | Phase 16 | Pending |
| API-03 | Phase 16 | Pending |
| API-04 | Phase 16 | Pending |
| API-05 | Phase 16 | Pending |
| API-06 | Phase 16 | Pending |
| API-07 | Phase 16 | Pending |
| API-08 | Phase 16 | Pending |
| CLN-01 | Phase 17 | Pending |
| CLN-02 | Phase 17 | Pending |
| CLN-03 | Phase 17 | Pending |
| CLN-04 | Phase 17 | Pending |
| CLN-05 | Phase 17 | Pending |
| CLN-06 | Phase 17 | Pending |
| DOC-01 | Phase 18 | Pending |
| DOC-02 | Phase 18 | Pending |
| DOC-03 | Phase 18 | Pending |
| DOC-04 | Phase 18 | Pending |

**Coverage:**
- v1.4 requirements: 23 total
- Mapped to phases: 23
- Unmapped: 0 ✓

**Phase distribution:**
- Phase 15 (Infrastructure Foundation): 5 requirements
- Phase 16 (API Migration): 8 requirements
- Phase 17 (Cleanup): 6 requirements
- Phase 18 (Documentation): 4 requirements

---
*Requirements defined: 2026-02-09*
*Last updated: 2026-02-09 after roadmap creation — 100% coverage achieved*