Compare commits

...

1 Commits

Author SHA1 Message Date
7e3811eb7a docs: update README for Phase 3 infrastructure completion
Update README to reflect completed Phase 3 infrastructure layer:
- Documented ModbusRelayController, MockRelayController, SqliteRelayLabelRepository, and HealthMonitor implementations
- Added testing coverage details (20+ tests across infrastructure components)
- Updated architecture diagrams and project structure
- Changed task reference to tasks.org format
- Updated dependency list with production infrastructure dependencies

Ref: Phase 3 tasks in specs/001-modbus-relay-control/tasks.org
2026-01-22 00:57:11 +01:00

125
README.md
View File

@@ -62,33 +62,59 @@ STA will provide a modern web interface for controlling Modbus-compatible relay
- RelayController and RelayLabelRepository trait definitions
- Complete separation from infrastructure concerns (hexagonal architecture)
### Planned - Phases 3-8
- 📋 Modbus TCP client with tokio-modbus (Phase 3)
- 📋 Mock controller for testing (Phase 3)
- 📋 Health monitoring service (Phase 3)
### Phase 3 Complete - Infrastructure Layer
- ✅ T028-T029: MockRelayController tests and implementation
- ✅ T030: RelayController trait with async methods (read_state, write_state, read_all, write_all)
- ✅ T031: ControllerError enum (ConnectionError, Timeout, ModbusException, InvalidRelayId)
- ✅ T032: MockRelayController comprehensive tests (6 tests)
- ✅ T025a-f: ModbusRelayController implementation (decomposed):
- Connection setup with tokio-modbus
- Timeout-wrapped read_coils and write_single_coil helpers
- RelayController trait implementation
- ✅ T034: Integration test with real hardware (uses #[ignore] attribute)
- ✅ T035-T036: RelayLabelRepository trait and SQLite implementation
- ✅ T037-T038: MockRelayLabelRepository for testing
- ✅ T039-T040: HealthMonitor service with state tracking
#### Key Infrastructure Features Implemented
- **ModbusRelayController**: Thread-safe Modbus TCP client with timeout handling
- Uses `Arc<Mutex<Context>>` for concurrent access
- Native Modbus TCP protocol (MBAP header, no CRC16)
- Configurable timeout with `tokio::time::timeout`
- **MockRelayController**: In-memory testing without hardware
- Uses `Arc<Mutex<HashMap<RelayId, RelayState>>>` for state
- Optional timeout simulation for error handling tests
- **SqliteRelayLabelRepository**: Compile-time verified SQL queries
- Automatic migrations via SQLx
- In-memory mode for testing
- **HealthMonitor**: State machine for health tracking
- Healthy -> Degraded -> Unhealthy transitions
- Recovery on successful operations
### Planned - Phases 4-8
- 📋 US1: Monitor & toggle relay states - MVP (Phase 4)
- 📋 US2: Bulk relay controls (Phase 5)
- 📋 US3: Health status display (Phase 6)
- 📋 US4: Relay labeling (Phase 7)
- 📋 Production deployment (Phase 8)
See [tasks.md](specs/001-modbus-relay-control/tasks.md) for detailed implementation roadmap (102 tasks across 9 phases).
See [tasks.org](specs/001-modbus-relay-control/tasks.org) for detailed implementation roadmap.
## Architecture
**Current:**
- **Backend**: Rust 2024 with Poem web framework
- **Backend**: Rust 2024 with Poem web framework (hexagonal architecture)
- **Configuration**: YAML-based with environment variable overrides
- **API**: RESTful HTTP with OpenAPI documentation
- **CORS**: Production-ready configurable middleware with security validation
- **Middleware Chain**: Rate Limiting CORS Data injection
- **Middleware Chain**: Rate Limiting -> CORS -> Data injection
- **Modbus Integration**: tokio-modbus for Modbus TCP communication
- **Persistence**: SQLite for relay labels with compile-time SQL verification
**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
@@ -205,48 +231,65 @@ sta/ # Repository root
│ │ ├── lib.rs - Library entry point
│ │ ├── main.rs - Binary entry point
│ │ ├── startup.rs - Application builder and server config
│ │ ├── settings/ - Configuration module
│ │ │ ├── mod.rs - Settings aggregation
│ │ │ └── cors.rs - CORS configuration (NEW in Phase 0.5)
│ │ ├── telemetry.rs - Logging and tracing setup
│ │ ├── domain/ - Business logic (NEW in Phase 2)
│ │ │ ├── relay/ - Relay domain types, entity, and traits
│ │
│ │ ├── domain/ - Business logic layer (Phase 2)
│ │ │ ├── relay/ - Relay domain aggregate
│ │ │ │ ├── types/ - RelayId, RelayState, RelayLabel newtypes
│ │ │ │ ├── entity.rs - Relay aggregate
│ │ │ │ ├── controller.rs - RelayController trait
│ │ │ │ └── repository.rs - RelayLabelRepository trait
│ │ │ │ ├── entity.rs - Relay aggregate with state control
│ │ │ │ ├── controller.rs - RelayController trait & ControllerError
│ │ │ │ └── repository/ - RelayLabelRepository trait
│ │ │ ├── modbus.rs - ModbusAddress type with conversion
│ │ │ └── health.rs - HealthStatus state machine
│ │ ├── application/ - Use cases (planned Phase 3-4)
│ │
│ │ ├── application/ - Use cases and orchestration (Phase 3)
│ │ │ └── health/ - Health monitoring service
│ │ │ └── health_monitor.rs - HealthMonitor with state tracking
│ │ │
│ │ ├── infrastructure/ - External integrations (Phase 3)
│ │ │ ── persistence/ - SQLite repository implementation
│ │ │ ── modbus/ - Modbus TCP communication
│ │ │ │ ├── client.rs - ModbusRelayController (real hardware)
│ │ │ │ ├── client_test.rs - Hardware integration tests
│ │ │ │ └── mock_controller.rs - MockRelayController for testing
│ │ │ └── persistence/ - Database layer
│ │ │ ├── entities/ - Database record types
│ │ │ ├── sqlite_repository.rs - SqliteRelayLabelRepository
│ │ │ └── label_repository.rs - MockRelayLabelRepository
│ │ │
│ │ ├── presentation/ - API layer (planned Phase 4)
│ │ ├── settings/ - Configuration module
│ │ │ ├── mod.rs - Settings aggregation
│ │ │ └── cors.rs - CORS configuration
│ │ ├── route/ - HTTP endpoint handlers
│ │ │ ├── health.rs - Health check endpoints
│ │ │ └── meta.rs - Application metadata
│ │ └── middleware/ - Custom middleware
│ │ └── rate_limit.rs
│ │
│ ├── settings/ - YAML configuration files
│ │ ├── base.yaml - Base configuration
│ │ ├── development.yaml - Development overrides (NEW in Phase 0.5)
│ │ └── production.yaml - Production overrides (NEW in Phase 0.5)
│ │ ├── development.yaml - Development overrides
│ │ └── production.yaml - Production overrides
│ └── tests/ - Integration tests
│ └── cors_test.rs - CORS integration tests (NEW in Phase 0.5)
│ └── cors_test.rs - CORS integration tests
├── migrations/ - SQLx database migrations
├── src/ # Frontend source (Vue/TypeScript)
│ └── api/ - Type-safe API client
├── docs/ # Project documentation
│ ├── cors-configuration.md - CORS setup guide
│ ├── domain-layer.md - Domain layer architecture (NEW in Phase 2)
│ ├── domain-layer.md - Domain layer architecture
│ └── Modbus_POE_ETH_Relay.md - Hardware documentation
├── specs/ # Feature specifications
│ ├── constitution.md - Architectural principles
│ └── 001-modbus-relay-control/
│ ├── spec.md - Feature specification
│ ├── plan.md - Implementation plan
│ ├── tasks.md - Task breakdown (102 tasks)
│ ├── domain-layer-architecture.md - Domain layer docs (NEW in Phase 2)
│ ├── lessons-learned.md - Phase 2 insights (NEW in Phase 2)
── research-cors.md - CORS configuration research
│ ├── tasks.org - Task breakdown (org-mode format)
│ ├── data-model.md - Data model specification
│ ├── types-design.md - Domain types design
── domain-layer-architecture.md - Domain layer docs
│ └── lessons-learned.md - Phase 2/3 insights
├── package.json - Frontend dependencies
├── vite.config.ts - Vite build configuration
└── justfile - Build commands
@@ -258,17 +301,15 @@ sta/ # Repository root
- Rust 2024 edition
- Poem 3.1 (web framework with OpenAPI support)
- Tokio 1.48 (async runtime)
- tokio-modbus (Modbus TCP client for relay hardware)
- SQLx 0.8 (async SQLite with compile-time SQL verification)
- async-trait (async methods in traits)
- config (YAML configuration)
- tracing + tracing-subscriber (structured logging)
- governor (rate limiting)
- thiserror (error handling)
- serde + serde_yaml (configuration deserialization)
**Planned Dependencies:**
- tokio-modbus 0.17 (Modbus TCP client)
- SQLx 0.8 (async SQLite database access)
- mockall 0.13 (mocking for tests)
**Frontend** (scaffolding complete):
- Vue 3 + TypeScript
- Vite build tool
@@ -306,6 +347,26 @@ sta/ # Repository root
**Test Coverage Achieved**: 100% domain layer coverage with comprehensive test suites
**Phase 3 Infrastructure Testing:**
- **MockRelayController Tests**: 6 tests in `mock_controller.rs`
- Read/write state operations
- Read/write all relay states
- Invalid relay ID handling
- Thread-safe concurrent access
- **ModbusRelayController Tests**: Hardware integration tests (#[ignore])
- Real hardware communication tests
- Connection timeout handling
- **SqliteRelayLabelRepository Tests**: Database layer tests
- CRUD operations on relay labels
- In-memory database for fast tests
- Compile-time SQL verification
- **HealthMonitor Tests**: 15+ tests in `health_monitor.rs`
- State transitions (Healthy -> Degraded -> Unhealthy)
- Recovery from failure states
- Concurrent access safety
**Test Coverage Achieved**: Comprehensive coverage across all layers with TDD approach
## Documentation
### Configuration Guides