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

# 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

# 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

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