A visual guide to how ChatrixCD works under the hood.
💡 Quick Summary: ChatrixCD bridges Matrix (encrypted chat) and Semaphore UI (CI/CD automation) with a Python bot that handles commands, manages tasks, and provides a beautiful TUI.
📊 System Overview
🧩 Core Components
🤖 Bot Core (bot.py)
The Heart of ChatrixCD
Matrix client management
E2E encryption handling
Event processing
Auto-sync & device verification
⚡ Commands (commands.py)
Command Processing Engine
Command parsing & validation
Semaphore API integration
Task management
Response formatting
🖥️ TUI (tui.py)
Interactive Interface
Status monitoring
Room management
Device verification
Log viewing
⚙️ Config (config.py)
Configuration Manager
HJSON parsing
Schema validation
Auto-migration
Secure defaults
🚀 Semaphore (semaphore.py)
CI/CD Integration
REST API client
Task lifecycle management
Status monitoring
Log retrieval
📝 Messages (messages.py)
Response Templates
Varied greetings
Sassy responses
Auto-reload support
Emoji & formatting
🔄 Data Flow
1️⃣
User Sends Command
User types !cd run 1 2 in a Matrix room
🔐 Message is E2E encrypted if room is encrypted
2️⃣
Bot Receives & Decrypts
Bot receives message event, decrypts it (if encrypted), and parses the command
🔍 Command parser validates syntax and permissions
3️⃣
Request Confirmation
Bot fetches template details and sends confirmation message with reaction buttons
👍👎 User reacts with thumbs up/down
4️⃣
Execute Task
Bot makes API call to Semaphore UI to start the task
🚀 Task ID returned and tracked
5️⃣
Monitor & Update
Bot polls task status and sends updates back to the room
📊 Real-time status updates with colored indicators
6️⃣
Task Complete
Final status sent with completion time and success/failure indicators
✅❌ Success = 🎉, Failure = 😔
🔐 Security Architecture
🔒 E2E Encryption
Matrix-nio handles Olm/Megolm encryption automatically. All encrypted room messages are secure.
🔑 Key Storage
Encryption keys stored in store/ directory with proper file permissions.
🛡️ Device Verification
Supports emoji, QR code, and fingerprint verification for trusted devices.
🔐 OIDC/SSO
Native OIDC authentication with major identity providers.
🚫 Permission Control
Configurable allowed_rooms restricts bot to authorized spaces.
🔍 Audit Trail
All commands and actions logged for security auditing.
🎯 Design Principles
Principle
Implementation
🔄 Async First
All I/O operations use async/await for non-blocking execution
