Skip to content

Concepts

Understand the ideas and architecture behind cosalette.

These pages explain why things work the way they do — the mental models, design patterns, and architectural decisions that shape the framework.

  • Architecture

    Composition root, Inversion of Control, decorator registration, context injection, and the four-phase orchestration model.

    Architecture

  • Device Archetypes

    Three first-class device types — Command (@app.command()), Command & Control (@app.device()), and Telemetry (@app.telemetry()) — with error isolation.

    Device Archetypes

  • Hexagonal Architecture

    PEP 544 Protocol ports, three adapter registration forms, lazy imports, dry-run mode, and the dependency rule.

    Hexagonal Architecture

  • MQTT Topics

    Home Assistant-aligned flat hierarchy with six topic types: state, set, availability, error, global error, and app status.

    MQTT Topics

  • Configuration

    Type-safe pydantic-settings with layered precedence: CLI flags > env vars > .env > defaults. SecretStr for credentials.

    Configuration

  • Application Lifecycle

    Four-phase orchestration: Bootstrap → Wire → Run → Teardown, with signal handling and graceful shutdown.

    Application Lifecycle

  • Error Handling

    Structured JSON error payloads, fire-and-forget MQTT publication, per-device isolation, and pluggable error type mapping.

    Error Handling

  • Health & Availability

    App-level LWT crash detection, structured JSON heartbeats, per-device online/offline availability for Home Assistant.

    Health & Availability

  • Logging

    NDJSON structured logs for production, text for development. UTC timestamps, correlation metadata, zero external dependencies.

    Logging

  • Publish Strategies

    Decouple probing from publishing — Every, OnChange, threshold modes, composition with | and &, and edge cases.

    Publish Strategies

  • Signal Filters

    Handler-level data transformations — PT1 low-pass, Median, and 1€ adaptive filters for smoothing sensor noise.

    Signal Filters

  • Persistence

    Save device state across restarts with pluggable backends and composable save policies.

    Persistence

  • Testing

    Three-layer strategy (domain, device, integration) with MockMqttClient, FakeClock, AppHarness, and a pytest plugin.

    Testing

  • Registry Introspection

    Machine-readable snapshots of all registered devices, telemetry, commands, and adapters for diagnostics and tooling.

    Registry Introspection