# n8n Workflow Architecture This document provides a visual overview of the multi-agent AI system architecture. ## System Overview ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ N8N AI AGENT TEAM │ │ Homelab Management System │ └─────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │ MAIN WORKFLOWS │ └─────────────────────────────────────────────────────────────────────────┘ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ VISHNU CTO │ │BRAHMA NETWORK │ │ SHIVA DEVOPS │ │ Orchestrator │ │ Administrator │ │ Engineer │ │ │ │ │ │ │ │ Webhook ⚡ │ │ Schedule ⏰ │ │ Webhook ⚡ │ │ /critical- │ │ Every 15min │ │ /cicd- │ │ issue │ │ │ │ deploy │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ AI Analysis │ │ UniFi Health │ │ Plex Session │ │ & Delegate │ │ Check │ │ Check │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ Execute │ │ Network │ │ AI Deployment │ │ Workflow │───────▶│ Diagnostics │ │ Plan │ │ (Delegate) │ │ (ping/trace) │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ Can Deploy? │ │ Synthesize │ │ AI Analysis │ │ (IF check) │ │ Results │ │ (Brahma AI) │ └───┬───────┬───┘ └───────┬───────┘ └───────┬───────┘ │ │ │ │ YES NO ▼ ▼ │ │ ┌───────────────┐ ┌───────────────┐ ▼ ▼ │ Telegram │ │ Telegram │ ┌─────────┐ ┌──────────┐ │ Approval │ │ Report │ │ Docker │ │ Telegram │ │ Request │ └───────────────┘ │ Restart │ │ Blocked │ └───────────────┘ └─────────┘ └──────────┘ ┌───────────────────────────────┐ │ APPROVAL-HANDLER UTILITY │ │ │ │ Telegram Trigger (Messages) │ └───────────────┬───────────────┘ │ Parse Response │ ┌──────────┴──────────┐ │ SWITCH │ │ YES / NO / ? │ └──┬───────┬───────┬──┘ YES NO ? │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌─────┐ ┌──────┐ │ Execute │ │Deny │ │Explain│ │ Workflow │ │Log │ │ More │ └────┬─────┘ └──┬──┘ └───┬──┘ │ │ │ ▼ ▼ ▼ Telegram Telegram Telegram Confirm Denial Info ``` ## Workflow Interaction Diagram ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ TYPICAL INCIDENT RESPONSE FLOW │ └─────────────────────────────────────────────────────────────────────────┘ 1. DETECTION External System ──[Webhook]──▶ Vishnu CTO │ ▼ 2. ANALYSIS AI Agent analyzes "Network issue detected" │ ▼ 3. DELEGATION Execute Workflow Node Calls brahma-network.json │ ▼ 4. SPECIALIST WORK Brahma Network Workflow ┌─────────────────────┐ │ HTTP: Check UniFi │ │ CMD: Run diagnostics│ │ AI: Analyze results │ └──────────┬──────────┘ │ ▼ 5. REPORT BACK Returns to Vishnu (via workflow) │ ▼ 6. SYNTHESIS Vishnu combines reports Creates action plan │ ▼ 7. HUMAN APPROVAL Telegram Message ┌──────────────────────────────────────────┐ │ 🔱 Vishnu CTO - Issue Resolution │ │ │ │ Issue: Network connectivity degraded │ │ Severity: HIGH │ │ Delegated To: brahma-network │ │ │ │ Specialist Report: │ │ - UniFi AP offline │ │ - Suggest: Reboot access point │ │ │ │ Reply YES to approve or NO to decline │ └──────────────────────────────────────────┘ │ ▼ 8. USER RESPONSE "YES" │ ▼ Approval Handler Workflow activates ┌─────────────────────┐ │ Parse: YES │ │ Switch: Route to YES│ │ Execute: Run fix │ │ Telegram: Confirm │ └─────────────────────┘ │ ▼ 9. CONFIRMATION "✅ Action completed successfully" ``` ## Data Flow Architecture ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ DATA & CONTROL FLOW │ └─────────────────────────────────────────────────────────────────────────┘ External Triggers n8n Workflows External Systems ───────────────── ───────────── ──────────────── [CI/CD Pipeline] ──webhook──▶ [Shiva DevOps] │ ├──http──▶ [Plex Server] │ status check │ ├──cmd──▶ [Docker] │ restart │ └──msg──▶ [Telegram] [Schedule: 15min] ──trigger──▶ [Brahma Network] │ ├──http──▶ [UniFi Controller] │ health API │ ├──cmd──▶ [System] │ ping/trace │ └──msg──▶ [Telegram] [Monitoring Alert] ──webhook──▶ [Vishnu CTO] │ ├──exec──▶ [Other Workflows] │ delegate tasks │ └──msg──▶ [Telegram] [Telegram Bot] ──message──▶ [Approval Handler] │ ├──exec──▶ [Target Workflow] │ approved action │ └──msg──▶ [Telegram] confirmation [OpenAI API] ◀──────────────────── All AI Agent Nodes (GPT-4o-mini) (system prompts + context) ``` ## Node Type Distribution ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ NODE TYPE ANALYSIS │ └─────────────────────────────────────────────────────────────────────────┘ TRIGGERS (How workflows start): ├─ Webhook Trigger ████████ (2) vishnu-cto, shiva-devops ├─ Schedule Trigger ████ (1) brahma-network └─ Telegram Trigger ████ (1) approval-handler AI & INTELLIGENCE: └─ AI Agent (LangChain) ████████████ (3) vishnu, brahma, shiva LOGIC & PROCESSING: ├─ Code (JavaScript) ████████████ (5) parsing, decisions, synthesis ├─ IF Condition ████ (1) can-deploy check └─ Switch ████ (1) YES/NO/other routing EXTERNAL INTERACTIONS: ├─ HTTP Request ████████ (2) UniFi, Plex ├─ Execute Command ████████ (2) diagnostics, docker └─ Telegram Message ████████████████ (6) notifications WORKFLOW ORCHESTRATION: └─ Execute Workflow ████████ (2) delegation, approval execution RESPONSE: └─ Webhook Response ████████ (2) API replies TOTAL NODES: 29 across 4 workflows ``` ## Security & Safety Architecture ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ SAFETY MECHANISMS │ └─────────────────────────────────────────────────────────────────────────┘ Level 1: READ-ONLY Operations (Auto-approved) ├─ HTTP GET requests (UniFi status) ├─ Ping/traceroute diagnostics └─ Status checks (Plex sessions) Level 2: CONDITIONAL Execution (Logic gates) ├─ IF active sessions = 0 → proceed ├─ IF severity < critical → auto-handle └─ SWITCH user response → route accordingly Level 3: HUMAN APPROVAL Required (via Telegram) ├─ Docker restart/rebuild ├─ Configuration changes ├─ Critical severity issues └─ Multi-system impacts Level 4: FORBIDDEN (Not implemented) ├─ Database DELETE/UPDATE ├─ Data destruction ├─ User management └─ Security policy changes Environment Variables (Secure secrets): ├─ {{$env.TELEGRAM_CHAT_ID}} ├─ {{$env.OPENAI_API_KEY}} └─ Credential system for API keys ``` ## Scalability & Extension Points ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ EXTENSION ARCHITECTURE │ └─────────────────────────────────────────────────────────────────────────┘ Additional Agents (Easy to add): ├─ Saraswati (Database) ──┐ ├─ Ganesha (Security) ──┤ └─ Hanuman (Helpdesk) ──┤ │ ├──▶ Same pattern as existing agents │ • Trigger (webhook/schedule) │ • AI Agent (domain-specific) │ • Tools (HTTP/CMD) │ • Telegram (notify) │ └──▶ Vishnu delegates via Execute Workflow Service Integrations (Plug & Play): ├─ Add HTTP Request node → New service ├─ Add Execute Command → New diagnostics └─ Update AI prompt → New behaviors Notification Channels (Beyond Telegram): ├─ Email node ├─ Slack node ├─ Discord node └─ Custom webhooks ``` ## File Structure Summary ``` n8n-AI-Multiple-Agent-Team/ │ ├── workflows-export.json # Single file with all workflows │ └── files[] │ ├── vishnu-cto.json # 7 nodes, orchestration │ ├── brahma-network.json # 6 nodes, monitoring │ ├── shiva-devops.json # 9 nodes, deployment │ ├── saraswati-database.json # 6 nodes, database │ ├── ganesha-security.json # 7 nodes, security │ ├── hanuman-helpdesk.json # 8 nodes, support │ └── approval-handler.json # 7 nodes, approval │ ├── workflows/ │ ├── agents/ │ │ ├── vishnu-cto.json │ │ ├── brahma-network.json │ │ ├── shiva-devops.json │ │ ├── saraswati-database.json │ │ ├── ganesha-security.json │ │ └── hanuman-helpdesk.json │ └── utilities/ │ └── approval-handler.json │ ├── WORKFLOWS_IMPLEMENTATION.md # Usage guide └── WORKFLOW_ARCHITECTURE.md # This file ``` ## Key Design Principles 1. **Separation of Concerns** - Each agent has one primary role - Clear delegation boundaries - No overlapping responsibilities 2. **Human-in-the-Loop** - Approval required for destructive actions - Clear YES/NO decision points - Audit trail via Telegram messages 3. **Fail-Safe Defaults** - Read-only operations don't require approval - Conditional checks before execution - Rollback plans documented 4. **Cosmic Wisdom Architecture** - Vishnu (Preservation) → Stability first - Brahma (Creation) → Infrastructure focus - Shiva (Transformation) → Controlled change - Each reflects Hindu deity attributes 5. **Observable & Debuggable** - Telegram notifications at key points - JSON output for structured data - Clear workflow execution history ## Version Information - **Implementation Version:** 1.0 - **n8n Compatibility:** Latest (2024) - **AI Model:** GPT-4o-mini (OpenAI) - **Created:** 2024 - **Status:** Production-ready ✅