sta/README.md

# STA - Smart Temperature & Appliance Control

Web-based Modbus relay control system for managing 8-channel relay modules over TCP.

> **⚠️ Development Status**: This project is in early development. Core features are currently being implemented following a specification-driven approach.

## Overview

STA will provide a modern web interface for controlling Modbus-compatible relay devices, eliminating the need for specialized industrial software. The goal is to enable browser-based relay control with real-time status updates.

## Current Status

**Implemented:**
- ✅ Basic Rust web server with Poem framework
- ✅ Configuration system (YAML + environment variables)
- ✅ Modbus TCP settings structure
- ✅ Health check and metadata API endpoints
- ✅ OpenAPI documentation with Swagger UI
- ✅ Rate limiting middleware

**In Progress:**
- 🚧 Domain model for relay control (Phase 2)
- 🚧 Modbus TCP client implementation (Phase 3)

**Planned Features:**
- 📋 8-Channel Relay Control: Individual and bulk relay control (on/off/toggle)
- 📋 Real-Time Monitoring: Live relay state updates via HTTP polling
- 📋 Custom Labels: Name your relays for easy identification
- 📋 Health Monitoring: Connection status and device health tracking
- 📋 Vue 3 + TypeScript frontend

See [tasks.md](specs/001-modbus-relay-control/tasks.md) for detailed implementation roadmap.

## Architecture

**Current:**
- **Backend**: Rust 2024 with Poem web framework
- **Configuration**: YAML-based with environment variable overrides
- **API**: RESTful HTTP with OpenAPI documentation

**Planned:**
- **Modbus Integration**: tokio-modbus for Modbus TCP communication
- **Frontend**: Vue 3 with TypeScript
- **Deployment**: Backend on Raspberry Pi, frontend on Cloudflare Pages
- **Access**: Traefik reverse proxy with Authelia authentication
- **Persistence**: SQLite for relay labels and configuration

## Quick Start

### Prerequisites

- Rust 1.83+ (edition 2024)
- Just command runner

### Development

```bash
# Run development server
just run

# Run tests
just test

# Run linter
just lint

# Format code
just format

# Watch mode with bacon
bacon          # clippy-all (default)
bacon test     # test watcher
```

### Configuration

Edit `settings/base.yaml` for Modbus device settings:

```yaml
modbus:
  host: "192.168.0.200"
  port: 502
  slave_id: 0
  timeout_secs: 5

relay:
  label_max_length: 50
```

Override with environment variables:
```bash
APP__MODBUS__HOST=192.168.1.100 cargo run
```

## API Documentation

The server provides OpenAPI documentation via Swagger UI:
- Swagger UI: `http://localhost:8080/`
- OpenAPI Spec: `http://localhost:8080/openapi.json`

**Current Endpoints:**
- `GET /api/health` - Health check endpoint
- `GET /api/meta` - Application metadata

**Planned Endpoints (see spec):**
- `GET /api/relays` - List all relay states
- `POST /api/relays/{id}/toggle` - Toggle relay state
- `POST /api/relays/all/on` - Turn all relays on
- `POST /api/relays/all/off` - Turn all relays off
- `PUT /api/relays/{id}/label` - Set relay label

## Project Structure

**Current:**
```
src/
├── lib.rs           - Library entry point
├── main.rs          - Binary entry point
├── startup.rs       - Application builder and server configuration
├── settings.rs      - Configuration management
├── telemetry.rs     - Logging and tracing setup
├── route/           - HTTP endpoint handlers
│   ├── health.rs    - Health check endpoints
│   └── meta.rs      - Application metadata
└── middleware/      - Custom middleware
    └── rate_limit.rs

specs/               - Feature specifications and documentation
settings/            - YAML configuration files
```

**Planned (Hexagonal Architecture):**
```
src/
├── domain/          - Business logic and domain models (Phase 2)
├── application/     - Use cases and orchestration (Phase 3-4)
├── infrastructure/  - Modbus, persistence, external services (Phase 3)
└── presentation/    - API endpoints and DTOs (Phase 4)
```

## Technology Stack

**Currently Used:**
- Rust 2024 edition
- Poem 3.1 (web framework with OpenAPI support)
- Tokio 1.48 (async runtime)
- config (YAML configuration)
- tracing + tracing-subscriber (structured logging)
- governor (rate limiting)
- thiserror (error handling)

**Planned Dependencies:**
- tokio-modbus 0.17 (Modbus TCP client)
- SQLx 0.8 (async SQLite database access)
- mockall 0.13 (mocking for tests)

**Frontend** (planned):
- Vue 3 + TypeScript
- Vite build tool
- Axios (HTTP client)

## Documentation

- [Project Constitution](specs/constitution.md) - Architectural principles and development guidelines
- [Modbus Relay Control Spec](specs/001-modbus-relay-control/spec.md) - Feature specification
- [CLAUDE.md](CLAUDE.md) - Developer guide and code style rules

## License

This project is under the AGPL-3.0 license. You can find it in the [LICENSE.md](LICENSE.md) file.