zCode-CLI-X/ARCHITECTURE.md

zCode CLI X - Architecture Overview

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    zCode CLI X                              │
│  Agentic Coder with Z.AI + Telegram Integration             │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
    ┌───▼────┐        ┌─────▼────┐        ┌─────▼────┐
    │  CLI   │        │  Bot     │        │  Agent   │
    │  Mode  │        │  Mode    │        │  System  │
    └───┬────┘        └─────┬────┘        └─────┬────┘
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
    ┌───▼────┐        ┌─────▼────┐        ┌─────▼────┐
    │ Tools  │        │ Skills   │        │  Agents  │
    │        │        │          │        │          │
    │ Bash   │        │ Code     │        │ Coder    │
    │ File   │        │ Review   │        │ Architect│
    │ Web    │        │ Bug Fix  │        │ DevOps   │
    │ Git    │        │ Refactor │        │          │
    └───┬────┘        └─────┬────┘        └─────┬────┘
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
    ┌───▼────┐        ┌─────▼────┐        ┌─────▼────┐
    │  Z.AI  │        │ Telegram │        │  File    │
    │  API   │        │  API     │        │  System  │
    │        │        │          │        │          │
    │ GLM-5.1│        │ Webhook  │        │ Express  │
    │ Coding │        │ WS       │        │ Node.js  │
    │        │        │ Bot      │        │ File I/O │
    └────────┘        └──────────┘        └──────────┘

📦 Core Components

1. CLI Entry Point (bin/zcode.js)

• Command-line interface
• Options: --dev, --no-bot, --no-cli
• Version check and help

2. Orchestrator (src/zcode.js)

Initializes all components in order:

1. Environment validation
2. Configuration loading
3. API initialization
4. Tools loading
5. Skills loading
6. Agent loading
7. Bot initialization (optional)

3. Z.AI API Adapter (src/api/index.js)

• REST API client using Axios
• Streaming support
• Error handling
• Model management

4. Telegram Bot (src/bot/index.js)

• Express server for webhooks
• WebSocket for real-time updates
• Message processing
• Callback handling

5. Tools System (src/tools/)

• BashTool: Shell command execution
• FileEditTool: File operations with diff-aware editing
• WebSearchTool: Web search via DuckDuckGo API
• GitTool: Git operations (status, log, branch)

6. Skills System (src/skills/index.js)

• Load from JSON files
• Built-in skills: code_review, bug_fix, refactor, documentation, testing
• Categories: development, documentation, testing

7. Agents System (src/agents/index.js)

• AgentOrchestrator: Coordinates agent execution
• Agents:
  • Code Reviewer: Bug detection, security review
  • System Architect: Design patterns, architecture
  • DevOps Engineer: Deployment, CI/CD

8. Utilities (src/utils/)

• Logger: Winston-based logging
• Env Check: Environment variable validation

🔄 Message Flow

User (Telegram) → Webhook → Bot → Agent Processing
                                         ↓
                                    Tools Execution
                                         ↓
                                    Skills Application
                                         ↓
                                    Response Generation
                                         ↓
                                    User (Telegram)

🛠️ Tool Capabilities

BashTool

• Execute shell commands
• Output capture
• Error handling
• Timeout support

FileEditTool

• Read files
• Write files
• Edit files (diff-aware)
• Git diff integration

WebSearchTool

• Search web
• Get abstracts
• Related topics
• No API key required

GitTool

• Status
• Log
• Branch info

🧠 Agent Capabilities

Code Reviewer

• Bug detection
• Security review
• Performance analysis
• Code style

System Architect

• Architecture design
• Pattern selection
• Documentation
• Scalability

DevOps Engineer

• Deployment
• CI/CD pipelines
• Infrastructure
• Monitoring

📊 Data Flow

┌─────────────────┐
│   Configuration │
│  (.env, config) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   API Client    │
│  (Z.AI Adapter) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Agent System  │
│   (Orchestrator)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Tools         │
│   (Bash, File,  │
│    Web, Git)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Skills        │
│  (Code Review,  │
│   Bug Fix, etc) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Response Gen  │
│   (Z.AI Model)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Telegram Bot   │
│   (Send back)   │
└─────────────────┘

🔐 Security

• API key in .env file (not committed)
• Environment variable validation
• No hardcoded credentials
• Input sanitization

🚀 Deployment

Development

node bin/zcode.js --dev

Production

# systemd service
sudo systemctl start zcode

# Or manual
node bin/zcode.js --bot

Docker (Future)

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "bin/zcode.js", "--bot"]

📈 Scalability

• WebSocket for real-time updates
• Queue-based message processing
• Agent concurrency control
• File-based logging

🔄 Extensibility

• Easy to add new tools
• Plugin system for skills
• Agent registry
• Modular architecture

---

Built with ❤️ by zCode CLI X