devplatform/CLAUDE.md

# ClearGrow Development Platform

## System Overview

Self-hosted development platform for the ClearGrow IoT agricultural monitoring system.

**Architecture**: Distributed 4-VPS setup on Linode (see `ARCHITECTURE.md` for details)

| VPS | IP | Services | Status |
|-----|-----|----------|--------|
| **vps-git** | 139.144.29.179 | Nginx, PostgreSQL, Gitea | **Active** |
| **vps-track** | 170.187.143.45 | Nginx, YouTrack | **Active** |
| **vps-ci** | 173.230.138.66 | Nginx, TeamCity, Build Agent, Registry | **Active** |
| **vps-agents** | 45.79.204.236 | Agent Runner, Claude Code, Toolchains | **Active** (this server) |

**Service URLs**:
- **Gitea**: https://git.cleargrow.io (vps-git - 139.144.29.179)
- **YouTrack**: https://track.cleargrow.io (vps-track - 170.187.143.45)
- **TeamCity**: https://ci.cleargrow.io (vps-ci - 173.230.138.66)

## Repositories

| Repository | Path | Technology | Purpose |
|------------|------|------------|---------|
| **controller** | `/opt/repos/controller` | ESP-IDF (C) | ESP32-S3 touchscreen controller with Thread Border Router |
| **probe** | `/opt/repos/probe` | Zephyr (C) | nRF52840 wireless sensor probes |
| **docs** | `/opt/repos/docs` | Markdown | Technical documentation |
| **devplatform** | `/root/claude` | Config | Platform configuration and Claude Code setup |

## Quick Commands

```bash
# vps-git management (Gitea)
ssh -i ~/.ssh/cleargrow_ed25519 root@139.144.29.179
systemctl status vps-git
docker compose -f /opt/devplatform/docker-compose.yml ps
docker compose -f /opt/devplatform/docker-compose.yml logs -f

# vps-track management (YouTrack)
ssh -i ~/.ssh/cleargrow_ed25519 root@170.187.143.45
systemctl status vps-track
docker compose -f /opt/devplatform/docker-compose.yml ps
docker compose -f /opt/devplatform/docker-compose.yml logs -f

# vps-ci management (TeamCity)
ssh -i ~/.ssh/cleargrow_ed25519 root@173.230.138.66
systemctl status vps-ci
docker compose -f /opt/devplatform/docker-compose.yml ps
docker compose -f /opt/devplatform/docker-compose.yml logs -f

# vps-agents (this server) - Agent Runner
sudo systemctl status cleargrow-agent-runner
sudo journalctl -u cleargrow-agent-runner -f

# Controller firmware (ESP-IDF) - on vps-agents
cd /opt/repos/controller
source ~/esp/esp-idf/export.sh
idf.py build

# Probe firmware (Zephyr) - on vps-agents
cd /opt/repos/probe
west build -b nrf52840dk_nrf52840
```

## Code Style

### ESP-IDF (Controller)
- Use ESP-IDF component architecture
- Prefix component functions with component name (e.g., `wifi_manager_init()`)
- Use ESP_LOG macros for logging
- Store persistent data in NVS
- Follow FreeRTOS task patterns

### Zephyr (Probe)
- Use Zephyr devicetree for hardware abstraction
- Use Kconfig for configuration options
- Follow Zephyr coding style (4-space indent)
- Use power management APIs for sleep modes

### Documentation
- Follow Diátaxis framework (guides/reference/project)
- Use templates from `_templates/`
- Keep user docs separate from developer docs

## Project Architecture

### Controller Components
Key components in `/opt/repos/controller/components/`:
- `wifi_manager/` - WiFi connection and provisioning
- `display/` - LVGL UI and touch handling
- `thread_manager/` - Thread Border Router
- `sensor_hub/` - Sensor data aggregation from probes
- `network_api/` - REST API and MQTT publishing
- `settings/` - NVS-backed configuration

### Probe Architecture
Key files in `/opt/repos/probe/src/`:
- `thread_node.c` - Thread networking and CoAP client
- `sensor_manager.c` - Sensor polling and data aggregation
- `power_manager.c` - Sleep modes and battery monitoring

### Protocol
Probes communicate with controller via CoAP over Thread using TLV format.

## Testing

### Controller
```bash
# Unit tests (host-based)
cd /opt/repos/controller
idf.py --project-dir test build
./test/build/test_app

# Integration test on device
idf.py flash monitor
```

### Probe
```bash
cd /opt/repos/probe
west build -b native_posix -- -DCONFIG_TEST=y
./build/zephyr/zephyr.exe
```

## YouTrack Integration

Issue references in commit messages:
- `CG-123` - Links commit to issue
- `CG-123 #fixed` - Links and transitions to Fixed state
- `CG-123 #in-progress` - Links and transitions to In Progress

## Agent Workflow States

Issues flow through these YouTrack states:
1. **Backlog** - New issues
2. **Ready** - Specs complete, ready for agent
3. **In Progress** - Agent working
4. **Verify** - Code review
5. **Document** - Documentation updates
6. **Review** - User final review
7. **Done** - Closed

## Common Tasks

### Adding a new sensor type to probe
1. Add sensor driver to `probe/src/sensors/`
2. Register in `sensor_manager.c`
3. Add measurement type to TLV protocol
4. Update controller's `sensor_hub` to parse new type
5. Add UI display in controller's `display` component

### Adding a new REST endpoint to controller
1. Define handler in `network_api/api_handlers.c`
2. Register route in `network_api/network_api.c`
3. Document in `docs/reference/api/`

### Creating a new UI screen
1. Add screen file in `controller/components/display/screens/`
2. Register in screen manager
3. Document in `docs/reference/ui/`

## Debugging Tips

### Controller
- Use `idf.py monitor` for serial console
- Enable verbose logging: `esp_log_level_set("*", ESP_LOG_VERBOSE)`
- Use JTAG for hardware debugging

### Probe
- Use `west debug` for GDB debugging
- Enable RTT logging for non-intrusive debugging
- Check Thread state with `ot state` shell command

## Memory Constraints

### Controller (ESP32-S3)
- Internal SRAM: ~320KB
- PSRAM: 8MB (frame buffers, history, TFLite)
- Flash: 16MB

### Probe (nRF52840)
- RAM: 256KB
- Flash: 1MB
- Optimize for low power sleep modes