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
```bash
node bin/zcode.js --dev
```

### Production
```bash
# systemd service
sudo systemctl start zcode

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

### Docker (Future)
```dockerfile
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