This project follows a Pragmatic Hexagonal Architecture (Ports and Adapters). The core business logic is fully isolated from infrastructure concerns such as Spring, JDBC, and Ktor.
For a complete description of the architecture, layer rules, the Unit of Work pattern, and coding conventions, refer to:
Every new feature and every refactoring must comply with the principles defined in that document. In particular: services must never use @Transactional, all failable operations must return Either<DomainError, T>, and exceptions must never escape the DAO layer.
For the authentication model, filter flow, configuration, and test helpers, refer to:
A Kotlin-based Spring Boot application for managing and controlling smart home devices, focusing on climate monitoring and heating control. It integrates with providers like SwitchBot and Netatmo.
- Device Management: Track and manage various smart home devices.
- Area & Room Organization: Group devices into areas (rooms) for better management.
- Climate Monitoring: Fetch and store temperature and humidity data from sensors.
- Heating Control: Automated heating strategies (Comfort, Economy, Dynamic) based on sensor data and schedules.
- Provider Integration: Native support for:
- SwitchBot (Meter, Hub Mini)
- Netatmo (Smarther thermostats)
- Historical Data: Persistent storage for sensor readings and historical analysis.
- Security: API key-based security for endpoint protection.
- Caching: Redis-backed and database-persistent caching mechanisms for performance and reliability.
- Language: Kotlin 2.1 (JVM 21)
- Framework: Spring Boot 3.4
- Database: PostgreSQL
- Migration: Flyway
- Cache: Redis
- HTTP Client: Ktor
- Containerization: Docker
- Testing: JUnit 5, Kotest, RestAssured, MockK, Testcontainers
- Java 21
- Docker (optional, for running with containers)
- PostgreSQL & Redis
The application can be configured via src/main/resources/application.properties (or environment variables). Key configuration areas include:
- Database connection strings
- Redis configuration
- Provider API credentials (SwitchBot, Netatmo)
- Security API keys
To build the project:
./gradlew buildTo run the application:
./gradlew bootRunThe project has a comprehensive test suite (270+ tests) including unit and integration tests using Testcontainers.
./gradlew testsrc/main/kotlin/.../api/controllers: REST API endpoints.src/main/kotlin/.../api/domain: Core domain models and business logic.src/main/kotlin/.../api/providers: Integration with external device providers (SwitchBot, Netatmo).src/main/kotlin/.../api/services: Business services, including heating strategies.src/main/kotlin/.../api/persistence: Data access layer (JDBC/PostgreSQL).src/main/kotlin/.../api/schedulers: Background tasks for data fetching and climate control.src/main/resources/db/migration: Database schema evolution scripts.