unraid-docker-manager/.planning/research/ARCHITECTURE.md

# Architecture Research: Unraid GraphQL API Integration

**Domain:** n8n workflow system migration from Docker socket proxy to Unraid GraphQL API
**Researched:** 2026-02-09
**Confidence:** HIGH

## Integration Architecture Overview

### Current Architecture (Docker Socket Proxy)

```
┌─────────────────────────────────────────────────────────────┐
│                     n8n Workflow System                      │
├─────────────────────────────────────────────────────────────┤
│  Main Workflow (169 nodes)                                   │
│    ├─── Execute Workflow → Update Sub-workflow              │
│    ├─── Execute Workflow → Actions Sub-workflow             │
│    ├─── Execute Workflow → Logs Sub-workflow                │
│    ├─── Execute Workflow → Status Sub-workflow              │
│    └─── Execute Workflow → Matching Sub-workflow            │
│                                                              │
│  Sub-workflows call Docker API:                             │
│    HTTP Request → docker-socket-proxy:2375/v1.47/...        │
│    Execute Command → curl docker-socket-proxy:2375/...      │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│           docker-socket-proxy (tecnativa/...)                │
│           Security layer: Exposes only safe endpoints        │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                      Docker Engine                           │
│                  /var/run/docker.sock                        │
└─────────────────────────────────────────────────────────────┘
```

### Target Architecture (Unraid GraphQL API)

```
┌─────────────────────────────────────────────────────────────┐
│                     n8n Workflow System                      │
├─────────────────────────────────────────────────────────────┤
│  Main Workflow (169 nodes)                                   │
│    ├─── Execute Workflow → Update Sub-workflow              │
│    ├─── Execute Workflow → Actions Sub-workflow             │
│    ├─── Execute Workflow → Logs Sub-workflow                │
│    ├─── Execute Workflow → Status Sub-workflow              │
│    └─── Execute Workflow → Matching Sub-workflow            │
│                                                              │
│  Sub-workflows call Unraid GraphQL API:                     │
│    HTTP Request → UNRAID_HOST/graphql (POST)                │
│    Header Auth: x-api-key                                   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│               Unraid GraphQL API Endpoint                    │
│     https://192-168-x-x.hash.myunraid.net:8443/graphql      │
│     Authentication: x-api-key header                         │
│     Permission: DOCKER:UPDATE_ANY                            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                   Unraid Docker Service                      │
│            Native container management + status sync         │
└─────────────────────────────────────────────────────────────┘
```

**Key architectural change:** Single unified API replaces two-layer proxy system. Unraid GraphQL API provides both Docker operations AND native Unraid integration (update status sync).

## Component Modification Map

### Sub-workflows Requiring Modification

| Sub-workflow | Docker API Nodes | Operations | Complexity | Priority |
|--------------|------------------|------------|------------|----------|
| **n8n-update.json** | 9 nodes | Pull, stop, remove, create, start, inspect, cleanup | HIGH | 1 |
| **n8n-actions.json** | 4 nodes | List, start, stop, restart | LOW | 2 |
| **n8n-status.json** | 3 nodes | List, inspect | LOW | 3 |
| **n8n-logs.json** | 2 nodes (Execute Command) | Container logs retrieval | LOW | 4 |
| **n8n-matching.json** | 0 nodes | Pure data transformation | NONE | N/A |
| **n8n-batch-ui.json** | 5 nodes (inherited) | Calls Update/Actions | NONE | N/A |
| **n8n-confirmation.json** | 0 nodes | Pure UI logic | NONE | N/A |

**Total impact:** 4 sub-workflows modified (18 Docker API nodes), 3 sub-workflows unchanged

### Sub-workflows NOT Requiring Modification

- **n8n-matching.json** — Container name matching logic operates on data shape, not API source
- **n8n-batch-ui.json** — Pure Telegram keyboard UI, no direct Docker API calls
- **n8n-confirmation.json** — Confirmation dialogs, no Docker operations

These workflows receive transformed data from modified workflows and operate on contracts (input/output shapes) that remain stable.

## Node Type Changes

### HTTP Request Node Pattern (Actions, Status)

**Before (Docker API):**
```javascript
// n8n HTTP Request node
{
  method: 'POST',
  url: 'http://docker-socket-proxy:2375/v1.47/containers/{{ $json.containerId }}/start',
  responseFormat: 'json'
}
```

**After (Unraid GraphQL API):**
```javascript
// n8n HTTP Request node
{
  method: 'POST',
  url: '={{ $env.UNRAID_HOST }}/graphql',
  authentication: 'genericCredentialType',
  genericAuthType: 'httpHeaderAuth',
  credential: 'Unraid API Key',  // Header Auth: x-api-key
  sendBody: true,
  bodyContentType: 'json',
  body: {
    query: 'mutation { docker { start(id: "{{ $json.unraidContainerId }}") { id state } } }'
  },
  options: {
    ignoreSSLIssues: true
  }
}
```

**Node type:** Same (HTTP Request), but parameters change
**Count:** ~15 HTTP Request nodes across Actions, Status, Update workflows

### Execute Command → HTTP Request (Logs, Update)

**Before (Execute Command with curl):**
```javascript
// n8n Execute Command node (Pull Image)
{
  command: '=curl -s --max-time 600 -X POST \'http://docker-socket-proxy:2375/v1.47/images/create?fromImage={{ encodeURIComponent($json.imageName) }}\' | tail -c 10000'
}
```

**After (HTTP Request with GraphQL mutation):**
```javascript
// n8n HTTP Request node
{
  method: 'POST',
  url: '={{ $env.UNRAID_HOST }}/graphql',
  authentication: 'genericCredentialType',
  genericAuthType: 'httpHeaderAuth',
  credential: 'Unraid API Key',
  sendBody: true,
  bodyContentType: 'json',
  body: {
    query: 'mutation { docker { updateContainer(id: "{{ $json.unraidContainerId }}") { id imageId state } } }'
  },
  timeout: 600000  // 10 minutes
}
```

**Node type change:** Execute Command → HTTP Request
**Count:** 3 Execute Command nodes (1 in Update for image pull, 2 in Logs for log retrieval)
**Impact:** Simpler — no shell escaping, native n8n timeout handling, structured GraphQL errors

## Data Transformation Requirements

### Container ID Mapping

**Docker API format:**
- Container ID: 64-character hex string (`8a9907a245766012...`)
- Container names: Array with `/` prefix (`["/n8n"]`)

**Unraid GraphQL format:**
- Container ID: `PrefixedID` scalar — `{server_hash}:{container_hash}` (128 chars + colon)
  - Example: `1639d2f04f44841b...a558d85071fa23e0:8a9907a245766012...840cefdec67af6b7`
- Container names: Array WITH `/` prefix (`["/n8n"]`) — GraphQL returns Docker's raw value

**Mapping strategy:**

1. **Container matching (Matching sub-workflow):**
   - User input: "n8n" (plain name)
   - Docker API query: Returns names `["/n8n"]` → strip `/` for comparison
   - Unraid GraphQL query: Returns names `["/n8n"]` → strip `/` for comparison
   - **No change needed** — name matching logic already strips `/` prefix

2. **Container identification:**
   - Docker API: Use Docker container ID (64 chars)
   - Unraid GraphQL: Use Unraid PrefixedID (128+ chars)
   - **Strategy:** Store Unraid ID from initial query, pass through workflow
   - **Where:** Matching sub-workflow output, Update/Actions/Status inputs

3. **Workflow contract stability:**
   - Field name stays `containerId` throughout all workflows
   - Value changes from Docker ID → Unraid PrefixedID
   - No contract changes needed — ID is opaque token to workflows

### Response Shape Transformation

**Docker API response (GET /containers/json):**
```json
[
  {
    "Id": "8a9907a245766012741662a5840cefdec67af6b70e4c6f1629af7ef8f1ee2925",
    "Names": ["/n8n"],
    "Image": "n8nio/n8n:latest",
    "ImageID": "sha256:abc123...",
    "State": "running",
    "Status": "Up 2 hours"
  }
]
```

**Unraid GraphQL response:**
```json
{
  "data": {
    "docker": {
      "containers": [
        {
          "id": "1639d2f04f44841b...a558d85071fa23e0:8a9907a245766012...840cefdec67af6b7",
          "names": ["/n8n"],
          "image": "n8nio/n8n:latest",
          "imageId": "sha256:abc123...",
          "state": "RUNNING",
          "status": "Up 2 hours",
          "isUpdateAvailable": false
        }
      ]
    }
  }
}
```

**Key differences:**

| Field | Docker API | Unraid GraphQL | Impact |
|-------|------------|----------------|--------|
| Container ID | `Id` | `id` | Lowercase (minor) |
| ID format | 64 hex chars | PrefixedID (128+) | Length check updates |
| Names | `Names` | `names` | Lowercase (minor) |
| Image ID | `ImageID` | `imageId` | Lowercase (minor) |
| State | `"running"` (lowercase) | `"RUNNING"` (uppercase) | Case handling in comparisons |
| Status | `Status` | `status` | Lowercase (minor) |
| Update available | Not available | `isUpdateAvailable` | NEW field (benefit!) |

**Transformation pattern:**

Add a **"Normalize Container Data"** Code node after Unraid GraphQL queries to map to workflow's expected shape:

```javascript
// Code node: Normalize Unraid GraphQL Response
const graphqlResponse = $input.item.json;

// Check for GraphQL errors first
if (graphqlResponse.errors) {
  throw new Error(`GraphQL error: ${graphqlResponse.errors.map(e => e.message).join(', ')}`);
}

// Extract containers from GraphQL response structure
const containers = graphqlResponse.data?.docker?.containers || [];

// Map to workflow's expected format
return containers.map(c => ({
  json: {
    containerId: c.id,           // Unraid PrefixedID
    containerName: (c.names?.[0] || '').replace(/^\//, ''),  // Strip leading /
    imageName: c.image,
    imageId: c.imageId,
    state: c.state.toLowerCase(), // RUNNING → running (for existing comparisons)
    status: c.status,
    updateAvailable: c.isUpdateAvailable || false  // NEW
  }
}));
```

**Where to add:** After every `docker.containers` GraphQL query in:
- Status sub-workflow (container list query)
- Matching sub-workflow (container list for matching)
- Actions sub-workflow (container list before action)

## Integration Patterns

### Pattern 1: Direct Mutation (Simple Operations)

**Use for:** Start, stop, restart, pause (single-step operations)

**Before (Docker API):**
```javascript
// HTTP Request node: POST /containers/{id}/start
// Response: HTTP 204 No Content (empty body)
// Success check: response.statusCode === 204
```

**After (Unraid GraphQL):**
```javascript
// HTTP Request node: POST /graphql
// Body: { query: 'mutation { docker { start(id: "...") { id state } } }' }
// Response: { data: { docker: { start: { id: "...", state: "RUNNING" } } } }
// Success check: response.data?.docker?.start?.state === "RUNNING"
```

**Error handling:**
- Docker API: HTTP status codes (404 = not found, 304 = already running)
- Unraid GraphQL: `response.errors[]` array with structured error messages
- **New pattern:** Check `response.errors` first, then validate `response.data` structure

**Example implementation (Actions sub-workflow):**

```javascript
// Code node: Validate Start Result
const response = $input.item.json;

// Check GraphQL errors
if (response.errors) {
  const errorMsg = response.errors.map(e => e.message).join(', ');
  return {
    json: {
      success: false,
      message: `Start failed: ${errorMsg}`,
      action: 'start'
    }
  };
}

// Validate response structure
const startResult = response.data?.docker?.start;
if (!startResult) {
  return {
    json: {
      success: false,
      message: 'Invalid GraphQL response: missing start result',
      action: 'start'
    }
  };
}

// Success
return {
  json: {
    success: true,
    action: 'start',
    containerId: startResult.id,
    state: startResult.state,
    message: 'Container started successfully'
  }
};
```

### Pattern 2: Complex Multi-Step Operations (Update Workflow)

**Docker API approach (9 nodes):**
1. Get container list → Find container
2. Inspect container → Extract config
3. Pull image (Execute Command with curl)
4. Inspect new image → Get digest
5. Stop container
6. Remove container
7. Create container (with old config)
8. Start container
9. Remove old image

**Unraid GraphQL approach (1-2 nodes):**
1. Call `updateContainer` mutation → Unraid handles all steps atomically
2. (Optional) Query container status after update

**Simplification:**

```javascript
// Single HTTP Request node: Update Container
{
  method: 'POST',
  url: '={{ $env.UNRAID_HOST }}/graphql',
  authentication: 'genericCredentialType',
  genericAuthType: 'httpHeaderAuth',
  credential: 'Unraid API Key',
  sendBody: true,
  bodyContentType: 'json',
  body: {
    query: 'mutation { docker { updateContainer(id: "{{ $json.containerId }}") { id imageId state isUpdateAvailable } } }'
  },
  timeout: 600000  // 10 minutes (pull can be slow)
}

// Code node: Validate Update Result
const response = $input.item.json;

if (response.errors) {
  const errorMsg = response.errors.map(e => e.message).join(', ');
  return {
    json: {
      success: false,
      updated: false,
      message: `Update failed: ${errorMsg}`
    }
  };
}

const updateResult = response.data?.docker?.updateContainer;
if (!updateResult) {
  return {
    json: {
      success: false,
      updated: false,
      message: 'Invalid GraphQL response'
    }
  };
}

// Check if update was needed
if (updateResult.isUpdateAvailable === false) {
  return {
    json: {
      success: true,
      updated: false,
      message: 'Container is already up to date'
    }
  };
}

// Success
return {
  json: {
    success: true,
    updated: true,
    message: `Container updated successfully`,
    newImageId: updateResult.imageId,
    state: updateResult.state
  }
};
```

**Impact:** Update sub-workflow shrinks from 34 nodes to ~15-20 nodes (remove 9 Docker API nodes, add 1-2 GraphQL nodes + data normalization)

**Benefit:** Unraid's `updateContainer` handles image pull, container stop/remove/create/start atomically AND syncs update status internally (solves v1.3's "apply update" badge issue automatically).

### Pattern 3: Log Retrieval (Logs Sub-workflow)

**Before (Execute Command):**
```javascript
// Execute Command node: Get Logs
{
  command: '=curl -s "http://docker-socket-proxy:2375/v1.47/containers/{{ $json.containerId }}/logs?stdout=true&stderr=true&tail={{ $json.lineCount || 50 }}"'
}
```

**After (Unraid GraphQL):**
```javascript
// HTTP Request node: Query Logs
{
  method: 'POST',
  url: '={{ $env.UNRAID_HOST }}/graphql',
  authentication: 'genericCredentialType',
  genericAuthType: 'httpHeaderAuth',
  credential: 'Unraid API Key',
  sendBody: true,
  bodyContentType: 'json',
  body: {
    query: 'query { docker { logs(id: "{{ $json.containerId }}", tail: {{ $json.lineCount || 50 }}) { entries } } }'
  }
}

// Code node: Format Logs
const response = $input.item.json;

if (response.errors) {
  throw new Error(`Log retrieval failed: ${response.errors.map(e => e.message).join(', ')}`);
}

const logData = response.data?.docker?.logs;
if (!logData) {
  throw new Error('Invalid GraphQL response: missing logs');
}

const logs = logData.entries || [];

return {
  json: {
    success: true,
    logs: logs.join('\n'),
    lineCount: logs.length
  }
};
```

**Benefit:** Native GraphQL logs query returns structured data (array of log entries) instead of raw Docker log format with control characters. Simpler parsing.

## Modified vs. New Components

### Modified Components

| Component | File | Modification Type | Node Count Change | Reason |
|-----------|------|-------------------|-------------------|--------|
| Container List Query | n8n-status.json | Replace HTTP Request URL + add normalization node | 3 → 4 nodes | GraphQL endpoint + response shape |
| Container Actions | n8n-actions.json | Replace HTTP Request URLs + update mutation body | 4 → 5 nodes | GraphQL mutations + error handling |
| Container Update | n8n-update.json | Replace 9 Docker API nodes with 2 GraphQL nodes | 34 → 27 nodes | Unraid atomic update |
| Container Logs | n8n-logs.json | Replace Execute Command with HTTP Request | 2 → 3 nodes | Native logs query + formatting |
| Container Matching | n8n-matching.json | Add normalization node after list query | 23 → 24 nodes | Data shape consistency |

**Total node count change:** 290 nodes → ~284 nodes (net reduction of ~6 nodes)

### New Components

| Component | Purpose | Where Added | Why New |
|-----------|---------|-------------|---------|
| Normalize Container Data | Map GraphQL response to workflow contract | All modified sub-workflows | Data shape consistency |
| GraphQL Error Handler | Validate `response.errors` array | Inline in validation Code nodes | GraphQL-specific error handling |
| Container ID Resolver | Map container name → Unraid PrefixedID | n8n-matching.json | ID format difference |

**Pattern:** Each modified sub-workflow gains 1-2 new Code nodes for normalization/validation.

## Suggested Build Order

### Phase 1: Infrastructure (Low Risk) — Already Complete

1. **Credential setup** — Completed in Phase 14
   - `.env.unraid-api` file
   - n8n Header Auth credential
   - Test query validated
   - Network connectivity proven (myunraid.net relay)

2. **Data normalization library** — Create reusable template
   - Build "Normalize Unraid Response" Code node
   - Test with Phase 14's test query
   - Template ready for copy-paste into sub-workflows

### Phase 2: Simple Sub-workflows (Low Complexity)

**Order:** Actions → Status → Logs → Matching

3. **Actions sub-workflow** (4 Docker API nodes → 5 GraphQL nodes)
   - Start/stop/restart mutations
   - Direct 1:1 mapping
   - Add normalization + error handling
   - Test: `start <container>`, `stop <container>`, `restart <container>`

4. **Status sub-workflow** (3 Docker API nodes → 4 GraphQL nodes)
   - Container list query
   - Single container query
   - Add normalization
   - Test: `status`, tap container in list

5. **Logs sub-workflow** (2 Execute Command → 3 HTTP Request)
   - Logs query with tail parameter
   - Add formatting Code node
   - Test: `logs <container>`

6. **Matching sub-workflow** (0 API nodes → 1 normalization node)
   - Container list source changes (inherited from Status)
   - Add normalization if not already present
   - Test: All name matching patterns

### Phase 3: Complex Sub-workflow (High Impact)

7. **Update sub-workflow** (9 Docker API nodes → 2 GraphQL nodes)
   - Replace multi-step Docker API flow with single `updateContainer` mutation
   - Unraid handles atomic update AND status sync
   - Validate success/failure cases
   - Test: `update <container>`, verify image pull + recreate + status cleared

### Phase 4: Dependency Cleanup (Post-Integration)

8. **Remove docker-socket-proxy dependency**
   - Update Docker Compose / Unraid template
   - Remove container from deployment
   - Remove volume mount for Docker socket
   - Update architecture docs

### Phase 5: Validation

9. **Full workflow testing**
   - All text commands (status, start, stop, restart, update, logs)
   - All inline keyboard flows (tap container → action)
   - Batch operations (stop multiple, update all)
   - Error cases (invalid container, network failure, API errors)
   - Verify Unraid update badges clear automatically after bot updates

**Rationale:** Start simple (Actions = 4 nodes, low risk), build confidence, tackle complex Update workflow last when patterns are proven.

## What NOT to Change

### Stable Components (DO NOT MODIFY)

1. **Main workflow structure** — Keyword Router, Auth IF, Correlation ID generator
   - Reason: No Docker API calls, pure orchestration logic

2. **Sub-workflow contracts** — Input/output shapes remain the same
   - Example: Update sub-workflow still receives `{ containerId, containerName, chatId, messageId, responseMode }`
   - Reason: Preserves integration points with main workflow
   - Note: `containerId` value changes (Docker ID → Unraid PrefixedID) but field name/type stable

3. **Telegram response nodes** — All "Send Message" and "Edit Message" nodes
   - Reason: User-facing messages, no Docker/Unraid API dependency

4. **Matching logic algorithm** — Container name matching strategy
   - Reason: Operates on container names array, agnostic to API source
   - Note: Data SOURCE changes, algorithm does not

5. **Batch UI logic** — Selection keyboard, bitmap encoding
   - Reason: Pure UI state management, no Docker operations

6. **Confirmation dialogs** — Stop/update confirmation flows
   - Reason: Pure UI logic, orchestration only

7. **Error logging patterns** — Structured error returns, correlation IDs
   - Reason: API-agnostic observability infrastructure

### Anti-Patterns to Avoid

- **Do NOT change sub-workflow contracts** — Main workflow dispatch nodes depend on stable input shapes
- **Do NOT mix Docker API and Unraid GraphQL** in same workflow — Pick one, commit fully, test, ship
- **Do NOT remove correlation IDs** — Observability is critical for debugging GraphQL errors
- **Do NOT change Telegram message formats** — User-facing stability matters
- **Do NOT optimize prematurely** — Get it working with Unraid GraphQL first, optimize later
- **Do NOT skip data normalization** — Consistent data shapes prevent cascading failures

## Risk Assessment

| Component | Risk Level | Mitigation |
|-----------|------------|------------|
| Actions sub-workflow | LOW | Simple 1:1 mutation mapping, test early |
| Status sub-workflow | LOW | Query-only, add normalization layer |
| Logs sub-workflow | LOW | GraphQL logs query is simpler than Docker API |
| Update sub-workflow | MEDIUM | Complex flow → atomic mutation (big simplification but needs thorough testing) |
| Container ID mapping | MEDIUM | ID format difference requires careful validation |
| Matching sub-workflow | LOW | No API changes, only data source changes |
| Main workflow | NONE | No modifications needed |
| docker-socket-proxy removal | LOW | Remove after all sub-workflows migrated, test thoroughly |

**Overall risk:** LOW-MEDIUM — Most changes are direct API replacements with simpler GraphQL equivalents. Update workflow is the only complex migration but Unraid's atomic operation actually simplifies the flow.

## Key Benefits of Migration

1. **Simplified Update Flow** — 9 Docker API nodes → 2 GraphQL nodes (atomic operation)
2. **Automatic Status Sync** — Unraid update badges clear automatically (solves v1.3's manual sync issue)
3. **Better Error Messages** — Structured GraphQL errors vs. HTTP status codes
4. **Native Integration** — Direct Unraid API vs. Docker proxy layer
5. **Update Detection** — `isUpdateAvailable` field enables proactive notifications
6. **Simpler Log Parsing** — Structured entries vs. raw Docker log format with control characters
7. **Security Improvement** — API key with granular permissions vs. Docker socket proxy
8. **Fewer Dependencies** — Remove docker-socket-proxy container from deployment

## Sources

- [Unraid GraphQL Schema](https://raw.githubusercontent.com/unraid/api/main/api/generated-schema.graphql) — Complete API specification (HIGH confidence)
- `.planning/phases/14-unraid-api-access/14-RESEARCH.md` — Phase 14 connectivity research (HIGH confidence)
- `ARCHITECTURE.md` — Existing workflow architecture, contracts (HIGH confidence)
- `n8n-workflow.json`, `n8n-*.json` — Actual workflow implementations (HIGH confidence)
- [n8n GraphQL Node Documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.graphql/) — HTTP Request patterns (HIGH confidence)
- [Docker API Documentation](https://docs.docker.com/engine/api/v1.47/) — Current Docker API patterns (HIGH confidence)

---
*Architecture research for: Unraid Docker Manager v1.4 — Unraid API Native*
*Researched: 2026-02-09*
*Confidence: HIGH — Unraid GraphQL schema verified, Phase 14 connectivity proven, workflow structure analyzed*