# Code Structure

## Build System
- **Type**: Python package (no pyproject.toml/setup.py — standalone scripts)
- **Linter**: ruff v0.8.0 (astral-sh)
- **Formatter**: ruff-format (built into ruff)
- **Pre-commit**: pre-commit hooks on cronjobs/**/*.py
- **No test framework configured yet** (pytest available but no test files)

## Key Files Inventory

### Python Applications

| File | Purpose | Lines |
|------|---------|-------|
| `cronjobs/run_cronjob_every_10mins.py` | Unified cronjob scheduler for all roles | ~250 |
| `cronjobs/team-workflow/import-dm-failed-job-analyze/run.py` | Failed job analysis with OpenClaw gateway | ~350 |
| `cronjobs/team-workflow/ng-serverless-oncall-sync/run.py` | Oncall sync script | ~200 |
| `skills/team-code-expert/feishu-card-parser/parse_card.py` | Feishu card parsing | ~150 |
| `skills/team-common/md2feishu/scripts/md2feishu.py` | Markdown to Feishu conversion | ~150 |
| `skills/team-common/clinic-api/clinic-token.sh` | Grafana clinic token script | ~50 |
| `skills/team-common/github-auth/scripts/github-auth.sh` | GitHub App auth script | ~50 |

### Bash Scripts

| File | Purpose |
|------|---------|
| `skills/setup/run.sh` | Agent self-configuration bootstrap |
| `skills/team-admin/backup-config/run.sh` | Config backup |
| `skills/team-admin/check-openclaw-status/run.sh` | Status check |
| `skills/team-admin/team-employee/run.sh` | Employee onboarding |
| `skills/team-admin/team-employee/debug_feishu.sh` | Feishu debug |
| `skills/team-code-expert/pr-review-daemon/run.sh` | PR review daemon runner |
| `skills/team-code-expert/tidbcloud-github-access/scripts/get-gh-token.sh` | GitHub token |
| `skills/team-common/clinic-api/clinic-token.sh` | Token retrieval |
| `skills/team-common/github-auth/scripts/github-auth.sh` | GitHub auth |

### Docker & Infrastructure

| File | Purpose |
|------|---------|
| `docker-compose/openclaw-team/docker-compose.yml` | 9+ container definitions |
| `.pre-commit-config.yaml` | Pre-commit hooks (ruff) |
| `ruff.toml` | Ruff linter config |
| `.github/workflows/feishu-pr-notify.yml` | GitHub Actions PR notifications |

### Cronjob Configurations

| File | Purpose |
|------|---------|
| `cronjobs/team-admin/cronjob.json` | Admin jobs (6 jobs) |
| `cronjobs/team-workflow/cronjob.json` | Workflow jobs (5 jobs) |
| `cronjobs/team-code-expert/cronjob.json` | Code expert jobs (2 jobs) |

### Agent Configuration (Markdown)

| File | Purpose |
|------|---------|
| `agents-bootstrap/personal.md` | Personal agent bootstrap |
| `agents-bootstrap/team-admin.md` | Admin agent bootstrap |
| `agents-bootstrap/team-workflow.md` | Workflow agent bootstrap |
| `agents-bootstrap/team-code-expert.md` | Code expert bootstrap |
| `agents-bootstrap/team-assist.md` | Assist agent bootstrap |
| `memories/*/IDENTITY.md, SOUL.md, USER.md, AGENTS.md, HEARTBEAT.md` | Per-role context |
| `memories/*/configuration.md` | Per-role config |

### Skills (SKILL.md directories)

| Skill | Team | Purpose |
|-------|------|---------|
| setup | shared | Agent self-configuration |
| daily-inspection | team-admin | Health check report |
| backup-config | team-admin | Config backup |
| check-openclaw-status | team-admin | Status check |
| team-employee | team-admin | Employee onboarding |
| github-pr | team-admin | GitHub PR operations |
| switch-provider | team-admin | AI provider switching |
| daily-stats | team-admin | Daily stats |
| pr-review-daemon | team-code-expert | PR review daemon |
| claude-code-dispatch | team-code-expert | Claude Code dispatch |
| tidbcloud-github-access | team-code-expert | GitHub access |
| feishu-card-parser | team-code-expert | Feishu card parsing |
| dataflow-service-e2e | team-code-expert | E2E testing |
| alert-log-analyzer | team-workflow | Alert analysis |
| import-dm-failed-job-analyze | team-workflow | Failed job analysis |
| ng-serverless-oncall-sync | team-workflow | Oncall sync |
| jira-issue-ops | team-common | Jira operations |
| clinic-api | team-common | Grafana clinic API |
| md2feishu | team-common | MD to Feishu |
| github-auth | team-common | GitHub auth |

### Knowledge Files

| File | Purpose |
|------|---------|
| `knowledge/README.md` | Knowledge base index |
| `knowledge/debugging.md` | Debugging guide |
| `knowledge/workflow.md` | Workflow documentation |
| `knowledge/team-context.md` | Team context |

## Design Patterns

### Cronjob Pattern
- **Location**: All cronjobs
- **Purpose**: Unified scheduling with schedule matching in Python
- **Implementation**: `run_cronjob_every_10mins.py` parses cron expressions and executes matching jobs from JSON config

### Agent Bootstrap Pattern
- **Location**: skills/setup/run.sh
- **Purpose**: Self-configuration based on role parameter
- **Implementation**: Bash script creates symlinks for skills, memories, and config files

### Role-Separation Pattern
- **Location**: docker-compose.yml, memories/, agents-bootstrap/
- **Purpose**: Isolated agents with specific responsibilities
- **Implementation**: Each role has its own container, memory files, and skill set

### Feishu-Only Communication Pattern
- **Location**: All cronjob error handling
- **Purpose**: All notifications via Feishu (no email/SMS)
- **Implementation**: Feishu API with tenant_access_token auth

## Critical Dependencies

### Python Standard Library
| Module | Usage |
|--------|-------|
| `json` | Config parsing, API payloads |
| `subprocess` | Job execution |
| `shlex` | Command parsing |
| `datetime` | Schedule matching |
| `pathlib` | File path resolution |
| `urllib.request` | Feishu API calls |
| `argparse` | CLI argument parsing |

### No External Python Packages
- All Python scripts use only the standard library
- No pip dependencies, no virtual environments required
- Python 3.11+ target

### External Services
| Service | Purpose |
|---------|---------|
| Feishu Open API | Messaging, wiki access |
| GitHub API | PR operations, repo access |
| Jira API | Issue tracking |
| Grafana API | Metrics access |
| MiniMax API | AI model inference |