portfolio/docs/TELEGRAM_CMS_SYSTEM.md

# 🚀 ULTIMATE TELEGRAM CMS SYSTEM - Implementation Plan

**Status:** Ready to implement  
**Duration:** ~15 minutes  
**Completion:** 8/8 workflows

---

## 🎯 System Overview

Your portfolio will be **fully manageable via Telegram** with these features:

### ✅ Commands (All work via Telegram Bot)

| Command | Function | Example |
|---------|----------|---------|
| `/start` | Main dashboard with quick action buttons | - |
| `/list projects` | Show all draft projects | `/list projects` |
| `/list books` | Show pending book reviews | `/list books` |
| `/search <term>` | Search projects & books | `/search nextjs` |
| `/stats` | Analytics dashboard (views, trends) | `/stats` |
| `/preview <ID>` | Show EN + DE translations before publish | `/preview 42` |
| `/publish <ID>` | Publish project or book (auto-detects type) | `/publish 42` |
| `/delete <ID>` | Delete project or book | `/delete 42` |
| `/deletereview <ID>` | Delete specific book review translation | `/deletereview 3` |
| `.review <HC_ID> <RATING> <TEXT>` | Create AI-powered book review | `.review427565 4 Great book!` |

---

## 📦 Workflow Architecture

```
┌─────────────────────────────────────────────────────────────┐
│            🤖 ULTIMATE TELEGRAM CMS (Master Router)          │
│  Handles: /start, /list, /search, /stats, /preview, etc.   │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   ┌────▼────┐          ┌────▼────┐          ┌────▼────┐
   │  Docker │          │  Book   │          │ Status  │
   │  Events │          │ Reviews │          │   API   │
   └─────────┘          └─────────┘          └─────────┘
   Auto-creates         AI prompts           Spotify +
   project drafts       for reviews          Discord +
                                             WakaTime
```

---

## 🛠️ Implementation Steps

### **1. Command Router** ✅ (DONE)
- File: `ULTIMATE-Telegram-CMS.json`
- Central command parser
- Switch routes to 10 different actions

### **2. /start Dashboard**
```telegram
🏠 Portfolio CMS Dashboard

📊 Quick Stats:
├─ 3 Draft Projects
├─ 2 Pending Reviews
└─ Last updated: 2 hours ago

⚡ Quick Actions:
┌────────────────┬────────────────┐
│ 📋 List Drafts │ 🔍 Search      │
└────────────────┴────────────────┘
┌────────────────┬────────────────┐
│ 📈 Stats       │ 🔄 Sync Now    │
└────────────────┴────────────────┘
```

### **3. /list Command**
```telegram
📋 Draft Projects (3):

1️⃣ #42 Portfolio Website
   Category: webdev
   Created: 2 days ago
   /preview42 · /publish42 · /delete42

2️⃣ #38 Suricata IDS
   Category: selfhosted
   Created: 1 week ago
   /preview38 · /publish38 · /delete38

───────────────────────────
/list books → See book reviews
```

### **4. /search Command**
```telegram
🔍 Search: "nextjs"

Found 2 results:

📦 Projects:
1. #42 - Portfolio Website (Next.js 15...)

📚 Books:
(none)
```

### **5. /stats Command**
```telegram
📈 Portfolio Stats (Last 30 Days)

🏆 Top Projects:
1. Portfolio Website - 1,240 views
2. Docker Setup - 820 views
3. Suricata IDS - 450 views

📚 Book Reviews:
├─ Total: 12 books
├─ This month: 3 reviews
└─ Avg rating: 4.2/5

⚡ Activity:
├─ Projects published: 5
├─ Drafts created: 8
└─ Reviews written: 3
```

### **6. /preview Command**
```telegram
👁️ Preview: Portfolio Website (#42)

🇬🇧 ENGLISH:
Title: Modern Portfolio with Next.js
Description: A responsive portfolio showcasing...

🇩🇪 DEUTSCH:
Title: Modernes Portfolio mit Next.js
Description: Ein responsives Portfolio das...

───────────────────────────
/publish42 · /delete42
```

### **7. Publish/Delete Logic**
- Auto-detects collection (projects vs book_reviews)
- Fetches item details from Directus
- Updates `status` field
- Sends confirmation with item title

### **8. AI Review Creator** ✅ (Already works!)
- `.review <HC_ID> <RATING> <TEXT>`
- Calls OpenRouter AI
- Generates EN + DE translations
- Creates draft in Directus

---

## 🔧 Technical Implementation

### **Workflow 1: ULTIMATE-Telegram-CMS.json**
**Nodes:**
1. Telegram Trigger (listens to messages)
2. Parse Command (regex matcher)
3. Switch Action (10 outputs)
4. Dashboard Node → Fetch stats from Directus
5. List Node → Query projects/books with pagination
6. Search Node → GraphQL search on Directus
7. Stats Node → Aggregate views/counts
8. Preview Node → Fetch translations
9. Publish Node → Update status field
10. Delete Node → Delete item + translations

### **Directus Collections Used:**
- `projects` (slug, title, category, status, technologies, translations)
- `book_reviews` (hardcover_id, rating, finished_at, translations)
- `tech_stack_categories` (name, technologies)

### **APIs Integrated:**
- ✅ Directus CMS (Bearer Token: `RF2Qytq...`)
- ✅ Hardcover.app (GraphQL)
- ✅ OpenRouter AI (Free models)
- ✅ Gitea (Self-hosted Git)
- ✅ Spotify, Discord Lanyard, Wakapi

---

## 🎨 Telegram UI Patterns

### **Inline Keyboards:**
```javascript
{
  "replyMarkup": "inlineKeyboard",
  "inlineKeyboard": {
    "rows": [
      {
        "buttons": [
          { "text": "📋 List", "callbackData": "list_projects" },
          { "text": "🔍 Search", "callbackData": "search_prompt" }
        ]
      }
    ]
  }
}
```

### **Pagination:**
```javascript
{
  "buttons": [
    { "text": "◀️ Prev", "callbackData": "list_page:1" },
    { "text": "Page 2/5", "callbackData": "noop" },
    { "text": "▶️ Next", "callbackData": "list_page:3" }
  ]
}
```

---

## 📊 Implementation Checklist

- [x] Command parser with 10 actions
- [ ] Dashboard (/start) with stats
- [ ] List command (projects/books)
- [ ] Search command (fuzzy matching)
- [ ] Stats dashboard (views, trends)
- [ ] Preview command (EN + DE)
- [ ] Unified publish logic (auto-detect collection)
- [ ] Unified delete logic with confirmation
- [ ] Error handling (try-catch all API calls)
- [ ] Logging (audit trail in Directus)

---

## 🚀 Deployment Steps

1. **Import workflow:** n8n → Import `ULTIMATE-Telegram-CMS.json`
2. **Set credentials:**
   - Telegram Bot: `DK0_Server` (already exists)
   - Directus Bearer: `RF2Qytq...` (already exists)
3. **Activate workflow:** Toggle ON
4. **Test commands:**
   ```
   /start
   /list projects
   /stats
   ```

---

## 🎯 Future Enhancements

1. **Media Upload** - Send image → "For which project?" → Auto-upload
2. **Scheduled Publishing** - `/schedule <ID> <date>`
3. **Bulk Operations** - `/bulkpublish`, `/archive`
4. **Webhook Monitoring** - Alert if workflows fail
5. **Multi-language AI** - Switch between OpenRouter models
6. **Undo Command** - Revert last action

---

## 📝 Notes

- Chat ID: `145931600` (hardcoded, change if needed)
- Timezone: Europe/Berlin (hardcoded in some workflows)
- AI Model: `openrouter/free` (cheapest, decent quality)
- Rate Limit: None (add if needed)

---

**Ready to deploy?** Import `ULTIMATE-Telegram-CMS.json` into n8n and activate it!