# System Architecture

## System Overview

The system is a multi-agent AI orchestration platform built on OpenClaw. It manages 9+ Docker containers, each running an OpenClaw gateway with a specific role. All inter-system communication flows through Feishu (no direct API exposure).

```mermaid
graph RL
    subgraph PhysicalHost["Physical Host (AWS EC2)"]
        subgraph Containers["Docker Containers"]
            Admin["team-admin\n(openclaw-team-admin)\nPort: none (local)"]
            Workflow["team-workflow\n(openclaw-team-assist)\nPort: 18794"]
            CodeExpert["team-code-expert\n(openclaw-team-code-expert)\nPort: 18791"]
            Members["Personal Agents\n(openclaw-{member})\nPorts: 18793-18825"]
        end
        Cron["Cron Daemon\n(run_cronjob_every_10mins.py)"]
        DockerNetwork["Docker Bridge Network"]
    end
    
    subgraph External["External Services"]
        Feishu["Feishu Cloud\n(Bot + Wiki)"]
        GitHub["GitHub\n(PRs + Repos)"]
        Jira["Jira\n(Issue Tracking)"]
        Grafana["Grafana\n(Metrics)"]
        MiniMax["MiniMax API\n(AI Model)"]
    end
    
    Admin --> Cron
    Workflow --> Feishu
    CodeExpert --> GitHub
    Admin --> DockerNetwork
    Workflow --> DockerNetwork
    CodeExpert --> DockerNetwork
    Members --> Feishu
    Admin --> Feishu
    CodeExpert --> Feishu
    Members --> MiniMax
    Admin --> MiniMax
    Workflow --> MiniMax
    CodeExpert --> MiniMax
    Admin --> Jira
    Admin --> Grafana
    CodeExpert --> Jira
    CodeExpert --> Grafana
    Feishu <--> GitHub
```

## Component Descriptions

### cronjobs/run_cronjob_every_10mins.py
- **Purpose**: Unified cronjob scheduler that runs all role-specific jobs
- **Responsibilities**: Parse cron expressions, check schedule match, execute commands, capture output, send Feishu alerts on failure
- **Dependencies**: json, subprocess, shlex, datetime, pathlib, urllib
- **Type**: Application (Python 3, no framework)

### docker-compose/openclaw-team/docker-compose.yml
- **Purpose**: Define all OpenClaw agent containers
- **Responsibilities**: Service definitions for 9+ containers (team-admin, team-workflow, team-code-expert, 7+ personal agents)
- **Key patterns**: network_mode: host (most), bridge network (code-expert), volume mounts for config
- **Type**: Infrastructure (Docker Compose)

### skills/setup/run.sh
- **Purpose**: Agent self-configuration bootstrap script
- **Responsibilities**: Link skills, copy memories, configure extraDirs in openclaw.json for each role
- **Supports**: personal, team-admin, team-workflow, team-code-expert
- **Type**: Application (Bash)

### agents-bootstrap/*.md
- **Purpose**: Agent initialization documents
- **Responsibilities**: Provide IDENTITY, SOUL, USER, AGENTS, HEARTBEAT context to OpenClaw agents
- **Type**: Configuration (Markdown)

### memories/*/configuration.md
- **Purpose**: Per-role environment and credential configuration
- **Responsibilities**: Document required env vars, API tokens, Feishu config, backup locations
- **Type**: Configuration (Markdown)

### skills/team-*/SKILL.md
- **Purpose**: Agent skill definitions
- **Responsibilities**: Describe what each skill does, usage instructions, dependencies
- **Type**: Configuration (Markdown)

### .github/workflows/feishu-pr-notify.yml
- **Purpose**: GitHub Actions workflow for PR event notifications
- **Responsibilities**: Send Feishu messages on PR opened/reopened/closed events
- **Type**: Infrastructure (GitHub Actions)

## Data Flow

### Daily Inspection Flow
```mermaid
sequenceDiagram
    participant Cron as Cron Daemon
    participant Py as run_cronjob_every_10mins.py
    participant OC as openclaw gateway
    participant Feishu as Feishu API
    
    Cron->>Py: Trigger (0:00 UTC)
    Py->>Py: Load cronjob.json
    Py->>Py: Match schedule
    Py->>OC: Execute daily-inspection script
    OC->>OC: Check container status
    OC->>Feishu: Send inspection report
```

### PR Review Flow
```mermaid
sequenceDiagram
    participant GH as GitHub
    participant OC as openclaw-team-code-expert
    participant LLM as MiniMax API
    participant Feishu as Feishu
    
    GH->>OC: PR event webhook
    OC->>OC: Fetch PR diff
    OC->>LLM: Send code for analysis
    LLM-->>OC: Review comments
    OC->>Feishu: Post review summary
```

## Integration Points

### External APIs
| Service | Purpose | Authentication |
|---------|---------|----------------|
| Feishu | Messaging & Wiki | App ID + App Secret (tenant token) |
| GitHub | PR access, repo ops | GitHub App (ID: 3002333) |
| Jira | Issue tracking | API Token |
| Grafana | Metrics access | API Token |
| MiniMax | AI model inference | API Key |

### Internal Data Flow
- **Config sync**: Host env vars → container env via docker-compose
- **Skill loading**: Skills symlinked from repo → ~/.openclaw/workspace/skills/
- **Memory sync**: Container-env-check script syncs host env to container
- **Logs**: CRONJOB_LOGS ~/CRONJOB_LOGS/*.log

## Infrastructure Components

### CDK/Terraform
- None (not IaC for this repo)

### Docker Compose Stacks
- **openclaw-team**: 9+ service definitions
- Image: openclaw-agent:latest (or tagged: openclaw-agent:2026.3.7)
- Logging: json-file driver, 10MB max, 3 files
- Restart: unless-stopped

### Deployment Model
- Manual deployment via `bash deploy.sh` in openclaw-team repo
- Cron daemon runs on physical host (not in containers)

### Networking
- Most containers: network_mode: host (bind directly to host ports)
- team-code-expert: bridge network (openclaw-network)
- No ports exposed to internet