agentic-mobile-control/docs/adr/0002-layered-hexagonal-architecture.md

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.