54 lines
2.1 KiB
Markdown
54 lines
2.1 KiB
Markdown
# ADR 0002: Layered Hexagonal Architecture
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
Upcoming milestones add semantic understanding, world state, skill retrieval,
|
|
workflow orchestration, multi-agent behavior, and cloud scheduling. Those
|
|
features introduce LLM, embedding, HTTP, MCP, storage, and plugin concerns that
|
|
must not leak into the device and domain contracts.
|
|
|
|
The `device-agent-runtime-foundation` design decision D7 records the governing
|
|
architecture: Hexagonal / Ports-and-Adapters with DDD-style domain boundaries.
|
|
|
|
## Decision
|
|
|
|
Use this dependency direction:
|
|
|
|
1. `core`: domain models and errors. No framework, LLM, HTTP, MCP, or external
|
|
device SDK dependencies.
|
|
2. `driver`: adapters over external device SDKs, implementing the `Driver`
|
|
contract.
|
|
3. `device`: device lifecycle management and active driver ownership.
|
|
4. `tools`: capability layer called by the runtime. Tools use device/driver
|
|
capabilities and do not import concrete drivers.
|
|
5. `perception`: produces `Scene` behind `PerceptionProvider`.
|
|
6. `storage`: persists timeline, task metadata, artifacts, and device config.
|
|
7. `runtime`: application layer. Planner and Executor orchestrate tools,
|
|
perception, storage, retries, and task state. LLM-backed planning first
|
|
enters here.
|
|
8. `api`: outermost transport adapter for REST, MCP, and future platform APIs.
|
|
|
|
Future milestones must build bottom-up through these boundaries. LLM and
|
|
transport dependencies may not be introduced into `core`, `driver`, `device`,
|
|
or `tools`.
|
|
|
|
## Alternatives Considered
|
|
|
|
Leaving the layering implicit was rejected because upcoming AI-heavy milestones
|
|
will otherwise tend to call LLM or transport APIs from convenient lower layers.
|
|
|
|
Adding lint enforcement now was deferred. The written architecture is the
|
|
current source of truth; mechanical enforcement can be added when a concrete
|
|
boundary violation or second-driver pressure appears.
|
|
|
|
## Consequences
|
|
|
|
The runtime can add smarter planning and richer perception without changing the
|
|
device capability contract. API and cloud concerns stay outside domain and
|
|
adapter layers. Future OpenSpec designs must state how they uphold this
|
|
dependency direction.
|