[GreenGrassBlueOcean]

Closes #732
Depends on #742

What is the problem

Three core integration files had grown into multi-responsibility monoliths that exceeded maintainable size boundaries and mixed unrelated concerns:

1. custom_components/myhome/config_flow.py (1,422 lines / ~65 KB):
   • Combined initial user/SSDP/USB discovery flows, reauth/reconfigure flows, shared-bus multi-gateway topology validation, F441M audio matrix / tuner / decoder pool options, and general gateway options inside a single file.
2. custom_components/myhome/gateway.py (1,383 lines):
   • Combined core session/frame routing with WHO=13 / WHO=1013 gateway model & firmware identification (_record_gateway_identity, conflict tracking, device-registry updates, worker trimming) and shared-bus cross-gateway topology correlation (_correlate_shared_bus_traffic, peer_gateways, topology_role).
3. custom_components/myhome/decoder_pool.py (1,028 lines):
   • Combined pure slot-allocation data structures, group membership bookkeeping, and diagnostic snapshot serialization with async bus operations (claim, release, set_group, restore_zones).

---

How is it solved

Decomposed all three monoliths into cohesive, single-responsibility modules meeting every explicit line-count budget from #732 while preserving all public entry points (MyhomeFlowHandler / MyhomeConfigFlow, MyhomeOptionsFlowHandler, MyHOMEGatewayHandler, DecoderPool), hassfest discovery rules, mypy --strict zero-error ratchet, and 100.0% statement coverage:

1. Config Flow Decomposition (config_flow.py: 1,422 $\rightarrow$ 333 lines, budget < 350):
   • custom_components/myhome/config_flow.py (333 lines): Core MyhomeFlowHandler (MyhomeConfigFlow) user/serial/custom setup steps (async_step_user, async_step_serial, async_step_custom, async_step_custom_manual) and async_get_options_flow.
   • custom_components/myhome/config_flow_discovery.py (482 lines): ConfigFlowDiscoveryMixin (SSDP discovery, discovery confirmation, reconfigure, reauth, connection test, port, and password steps).
   • custom_components/myhome/config_flow_topology.py (379 lines): ConfigFlowTopologyMixin and OptionsFlowTopologyMixin (shared-bus onboarding, secondary interface #4#<if> validation, and peer gateway selection).
   • custom_components/myhome/config_flow_audio.py (287 lines): OptionsFlowAudioMixin (F441M audio matrix input naming, tuner declaration, environment routing defaults, and decoder slot validation).
   • custom_components/myhome/config_flow_options.py (292 lines): MyhomeOptionsFlowHandler (re-exported from config_flow.py).
2. Gateway Decomposition (gateway.py: 1,383 $\rightarrow$ 640 lines, budget < 700):
   • custom_components/myhome/gateway.py (640 lines): Core gateway lifecycle, session orchestration, paced sweeps, and frame dispatch.
   • custom_components/myhome/identity.py (632 lines): GatewayIdentityMixin (WHO=13 Dimension 15/16/23/24 and WHO=1013 Dimension 1 model/firmware resolution, identity conflict repair issues, device-registry synchronization, and single-session worker trimming).
   • custom_components/myhome/topology.py (696 lines): GatewayTopologyMixin (shared-bus cross-gateway frame correlation, peer gateway discovery, and topology role helpers).
3. Decoder Pool Decomposition (decoder_pool.py: 1,028 $\rightarrow$ 434 lines, budget < 450):
   • custom_components/myhome/decoder_pool.py (434 lines): DecoderPool lifecycle and async slot/group operations (claim, release, set_group, restore_zones, update_slots).
   • custom_components/myhome/decoder_allocation.py (404 lines): DecoderAllocationMixin (slot allocation state, _set_group_locked, environment_owner, _environment_owners, and diagnostic snapshot building).
4. Architectural Validator Updates (scripts/verify_ha_standards.py):
   • Updated check_discovery_flows() and IQS Gold reconfiguration-flow rule to inspect config_flow*.py across the decomposed config flow package, and added decoder_allocation.py to RUNTIME_DATA_READERS.

How is it tested

• tests/test_config_flow.py, tests/test_config_flow_serial.py, tests/test_shared_bus_onboarding.py, tests/test_gateway.py (including test_replay_f461_who14_live_2026_10_18_gateway_identity), tests/test_gateway_identification.py, tests/test_decoder_pool.py, tests/test_where_usage_guard.py, and full 4,193-test suite: all passing with 100.0% statement coverage across every extracted module.
• scripts/typing_ratchet.py: mypy --strict: 0 error(s) in 0 module(s); baseline 0.
• scripts/verify_ha_standards.py: all 69 Python source files verified, 54/54 Home Assistant Platinum Quality Scale rules satisfied.
• scripts/sync_documentation.py --check and hassfest: 0 violations.

---

State Diagram

flowchart TD
    subgraph ConfigFlowPackage["Config & Options Flow Package"]
        CF["config_flow.py\nMyhomeFlowHandler (333 lines)"]
        CFD["config_flow_discovery.py\nConfigFlowDiscoveryMixin (482 lines)"]
        CFT["config_flow_topology.py\nConfigFlowTopologyMixin /\nOptionsFlowTopologyMixin (379 lines)"]
        CFA["config_flow_audio.py\nOptionsFlowAudioMixin (287 lines)"]
        CFO["config_flow_options.py\nMyhomeOptionsFlowHandler (292 lines)"]
        CFD --> CF
        CFT --> CF
        CFT --> CFO
        CFA --> CFO
        CF --> CFO
    end

    subgraph GatewayPackage["Gateway Handler Package"]
        GW["gateway.py\nMyHOMEGatewayHandler (640 lines)"]
        GWI["identity.py\nGatewayIdentityMixin (632 lines)\n(WHO 13 / WHO 1013)"]
        GWT["topology.py\nGatewayTopologyMixin (696 lines)\n(Shared-Bus Correlation)"]
        GWI --> GW
        GWT --> GW
    end

    subgraph DecoderPoolPackage["Audio Decoder Pool Package"]
        DP["decoder_pool.py\nDecoderPool (434 lines)"]
        DPA["decoder_allocation.py\nDecoderAllocationMixin (404 lines)"]
        DPA --> DP
    end

Loading

---

Where are the traces

• Gateway Identity & Shared-Bus Multi-Gateway Traces:
  • tests/fixtures/traces/f461_who14_live_2026-10-18/myhome_trace_F461_who14_live_2026-10-18.json (physical BTicino F461 2.0.11, kernel 5.10.35, distribution 2.26.4 WHO=13 Dims 15/16/23/24 + WHO=1013 Dim 1 134*15*5*0 replayed in tests/test_gateway.py::test_replay_f461_who14_live_2026_10_18_gateway_identity).
  • tests/fixtures/traces/f461_live_2026-10-15/myhome_trace_F461_live_2026-10-15.json (BTicino F461 WHO=13 code 200 + WHO=1013 code 134 disambiguation).
  • tests/fixtures/traces/oracle_h4684_gateway/myhome_trace_oracle_h4684_gateway_identification.json (H4684 WHO=13 / WHO=1013 identification sequence exercised via identity.py::GatewayIdentityMixin).
  • tests/fixtures/traces/issue_484/ & issue_486/ (H4890 + F454 shared-bus topology correlation exercised via topology.py::GatewayTopologyMixin).

---

What does the Oracle / Encyclopedia say

• WHO=13 vs. WHO=1013 Gateway Identification (identity.py & tests/golden/firmware_oracle.json):
  • Across the 12 emulated gateways in tests/golden/firmware_oracle.json, Linux-based gateways (F454 020051, F459 020105, F460 020012, F461 020011, MH202 010024, MyHomeServer1 028206) all reply to *#13**15## with shared family code 200 (*#13**15*200##), whereas *#1013*0*1## disambiguates the exact hardware model via bt_device (*#1013**1*51## for F454, *#1013**1*65## for F459, *#1013**1*134## for F461, *#1013**1*5## for MH202, *#1013**1*67## for MyHomeServer1, *#1013**1*19## for H4684, *#1013**1*12## for F453AV, *#1013**1*22## for F453, *#1013**1*4## for MH200, *#1013**1*44## for MH200N).
  • Isolating this multi-stage WHO=13 / WHO=1013 state machine in identity.py (GatewayIdentityMixin) keeps gateway.py focused strictly on session transport and frame routing.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!