HomeTom is an asynchronous smart-home orchestration system built around Domain-Driven Design and Onion Architecture. It manages devices, scenes and executions while using Home Assistant as the hardware abstraction layer.
Model the system around behaviour
The project separates three contexts:
- Device describes hardware capabilities and state synchronisation.
- Scene defines triggers, conditions and actions.
- Execution records runtime state, retry policies and outcomes.
This prevents API handlers and hardware clients from becoming the place where every business rule accumulates.
Keep infrastructure outside the domain
FastAPI receives requests and delegates work to the application layer. Domain code depends on interfaces rather than databases or Home Assistant. SQLAlchemy repositories and HTTP clients implement those interfaces at the edge.
trigger = schedule.next()
execution = orchestration.start(scene, trigger)
result = await workflow.run(execution)
await events.publish(result.events)The exact syntax is less important than the dependency direction: external systems can change without rewriting the rules that define a valid scene or execution.
Treat failure as a domain state
Networked hardware is slow and unreliable. Timeouts, retries and partial failures are normal operating conditions. The execution model records them explicitly, while domain events keep logging and notifications away from the main command path.
The result is not a promise that distributed hardware will always work. It is a system that can explain what happened and recover predictably when it does not.