docs: initialize project

Conversational Telegram bot for managing Docker containers on Unraid using natural language, powered by Claude API and n8n orchestration. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-28 16:24:42 -05:00
parent 1906b20039
commit b955096341
1 changed files with 71 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Unraid Docker Manager
+
+## What This Is
+
+A conversational Telegram bot that lets you manage Docker containers on your Unraid server using natural language. Think JARVIS for your homelab — ask questions, get status updates, and control containers all from your phone without needing to open a laptop.
+
+## Core Value
+
+When you get a container update notification or notice a service is down, you can immediately investigate and act from your phone through a natural conversation.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] Send a message to the bot and receive a response
+- [ ] Ask about container status ("how's Plex doing?")
+- [ ] Start a container by name
+- [ ] Stop a container by name
+- [ ] Restart a container by name
+- [ ] Update a container (pull new image, recreate)
+- [ ] View container logs with configurable line count (default 50)
+- [ ] Ask conversational questions ("what's using the most memory?")
+- [ ] Bot only responds to your Telegram user ID
+
+### Out of Scope
+
+- Taking over Unraid notifications — keep existing notification system, this bot is for control
+- Deploying new containers — manage existing only, not create new ones
+- Local LLM — N100 can't handle it well, using Claude API instead
+- Proactive monitoring/notifications — bot is reactive (you ask, it answers) for v1
+
+## Context
+
+**Environment:**
+- Unraid server with Intel N100 CPU, 32GB RAM
+- n8n already running and mostly unused — will use as orchestration layer
+- Multiple Docker containers running various services (Plex, Sonarr, etc.)
+
+**Current workflow:**
+- Unraid sends notifications when container updates are available
+- Currently need laptop/desktop to act on updates or troubleshoot
+- Want to be able to respond immediately from phone
+
+**User scenarios:**
+1. Get update notification → open Telegram → "update plex" → done
+2. Notice service not responding → "check sonarr logs" → see errors → "restart sonarr"
+3. Curious about system → "what containers are running?" or "what's using the most resources?"
+
+## Constraints
+
+- **Platform**: Must run on Unraid (Docker-based deployment)
+- **Orchestration**: Use n8n for workflow orchestration (already running)
+- **LLM**: Claude API for natural language understanding
+- **Auth**: Single user only — verify Telegram user ID
+- **Logs**: Support configurable line count, default to 50 lines
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Use Claude API over local LLM | N100 CPU can't run LLMs fast enough for good UX | — Pending |
+| Use n8n for orchestration | Already running, handles Telegram webhooks, reduces new infrastructure | — Pending |
+| Manage existing containers only | Keeps scope focused, deployment is complex and rarely needed from mobile | — Pending |
+| Single user auth via Telegram ID | Simple security model, only one person needs access | — Pending |
+
+---
+*Last updated: 2026-01-28 after initialization*