trail-mate/docs/specification/PRODUCT_COMPOSITION_ARCHITECTURE_SPEC.md

Product Composition Architecture Specification

Purpose

This specification defines how Trail Mate product targets assemble runtime, app services, presentation models, and renderers.

Phase 6 uses this specification to move object graph construction toward explicit target/app shell composition roots.

Core Rule

CompositionRoot wires.

It does not decide business behavior.

The product architecture responsibility chain is:

Target chooses.
Board describes.
Platform adapts.
Runtime schedules.
Capability provides.
Protocol interprets.
UseCase decides.
AppService coordinates.
PresentationModel projects.
Renderer draws.
CompositionRoot wires.

Composition Root Responsibilities

A composition root may:

• read target manifest or compile target identity
• select board package
• create platform adapter factories
• create runtime context
• create app services
• create presentation sources/sinks
• create presentation models
• create PresentationWorkspace
• create renderer shell
• connect lifecycle start/stop hooks

A composition root must not:

• interpret protocol payloads
• implement business decisions
• directly render UI widgets
• own packet parsing
• own GPS parsing
• own tile cache behavior
• own Chat message policy
• infer pending/failure state

Target App Shell

TargetAppShell owns:

• renderer lifecycle
• event loop integration
• presentation workspace binding
• input dispatch into presentation actions
• shell-specific timers
• shell startup/shutdown

TargetAppShell must not own:

• protocol interpretation
• board pin facts
• storage schema
• business policy
• platform adapter semantics

Platform Factory

Platform factories may create:

• radio adapter
• GPS byte stream
• BLE host adapter
• storage backend
• display driver host
• input driver host
• timer/clock/queue primitives

Platform factories must not:

• select product feature set
• interpret Meshtastic/MeshCore semantics
• create UI page business logic
• own AppService coordination

Board Package

Board packages describe hardware facts:

• pins
• buses
• power rails
• display dimensions
• available peripherals
• electrical constraints

Board packages must not:

• decide product features
• create app services
• interpret radio protocols
• render UI
• own runtime scheduling policy

Target Manifest

Target manifests are product configuration contracts.

They may select:

• board package
• platform profile
• shell profile
• capabilities
• authority sources
• BLE backend selection, including local, C6 companion, or none
• display orientation policy

They must not become arbitrary runtime configuration systems in Phase 6.

For ESP32-P4 plus ESP32-C6 products, the target selects the C6 wireless companion as a capability binding. The board only describes the C6 hardware facts. P4 remains the authority for Trail Mate business state.

AppContext Bridge

Existing AppContext is a legacy service locator.

Phase 6 may introduce:

• LegacyAppContextBridge
• AppServicesBundle
• PresentationBundle

The bridge must shrink over time. New code must not add unrelated service lookups to AppContext.

Object Lifetime

Target composition roots own static or long-lived objects.

No renderer may create app services.

No presentation model may create source/sink objects.

No source/sink may create renderer objects.

PresentationWorkspace may expose model pointers that are owned by the target composition root or app shell. It must not create those models.

Allowed Dependency Direction

Target/App Composition Root
  -> platform factories
  -> app services
  -> presentation sources/sinks
  -> presentation models
  -> presentation workspace
  -> renderer shell

Renderers may consume presentation snapshots and send presentation actions.

Renderers must not reach backward into platform factories, app-service construction, or board facts.

Exit Criteria

Phase 6 is successful when:

• each major target has an explicit composition root or documented legacy bridge
• PresentationWorkspace is assembled by target/app shell code
• AppContext usage is bounded
• product composition contracts exist
• checker prevents new object graph construction in renderer/page code
• target/board/platform wiring rules are documented and checked