Architecture Conformance Pass - 2026-02-07¶
Status¶
This document is a baseline snapshot and is superseded by:
docs/migration/05-architecture-conformance-pass-2026-02-07-followup.md
Use the follow-up document as the authoritative current status.
Scope¶
This pass checks migration docs against 02-island-boundaries-and-performance.md.
Reviewed docs:
docs/migration/00-overview.mddocs/migration/stock-import/00-stock-import-overview.mddocs/migration/platform-export/00-platform-export-overview.mddocs/migration/webshop/02-products.mddocs/migration/vehicle-data/02-vehicle-product-mapping.mddocs/migration/libraries/00-libraries-overview.mddocs/migration/libraries/06-shared-bundles.mddocs/migration/operations/00-cron-scheduler-operating-model.md
Executive Result¶
Overall status: Partial.
Highseverity findings: 3Mediumseverity findings: 3- Explicitly aligned areas: 3
Findings (Ordered By Severity)¶
| ID | Severity | Status | Finding | Evidence | Required Action |
|---|---|---|---|---|---|
| AR-001 | High | Conflict | Shared domain bundle strategy conflicts with anti-fragmentation policy. | docs/migration/00-overview.md:164, docs/migration/00-overview.md:175, docs/migration/libraries/00-libraries-overview.md:28, docs/migration/libraries/06-shared-bundles.md:38, docs/migration/02-island-boundaries-and-performance.md:64 |
Replace shared mutable domain bundles with island-local domain models and keep only capped shared package types. |
| AR-002 | High | Conflict | Cross-island communication is documented as REST-only, but baseline requires mixed sync/async contracts with outbox/inbox. | docs/migration/00-overview.md:24, docs/migration/00-overview.md:140, docs/migration/02-island-boundaries-and-performance.md:84, docs/migration/02-island-boundaries-and-performance.md:86 |
Update communication model docs to define event channels, publishers/consumers, idempotency keys, and replay behavior. |
| AR-003 | High | Gap | Wheel-set flows still describe runtime composition behavior; projection model and SLI targets are missing from the webshop product spec. | docs/migration/webshop/02-products.md:204, docs/migration/webshop/02-products.md:223, docs/migration/02-island-boundaries-and-performance.md:124, docs/migration/02-island-boundaries-and-performance.md:148 |
Add wheel_set_projection contract, refresh triggers, and p95 target enforcement to product docs. |
| AR-004 | Medium | Gap | Supplier/platform connector runtime controls are not explicit (idempotency, retries, DLQ, checkpoints). | docs/migration/stock-import/00-stock-import-overview.md:38, docs/migration/stock-import/00-stock-import-overview.md:69, docs/migration/platform-export/00-platform-export-overview.md:108, docs/migration/platform-export/00-platform-export-overview.md:124, docs/migration/02-island-boundaries-and-performance.md:73, docs/migration/02-island-boundaries-and-performance.md:154 |
Extend stock/platform docs with connector contract sections and queue policy details. |
| AR-005 | Medium | Gap | ERP middleware boundary is scoped, but no concrete ownership contract or API/event boundary spec is documented here. | docs/migration/00-overview.md:123, docs/migration/00-overview.md:136 |
Add a dedicated ERP boundary contract doc with ownership, APIs, failure handling, and SLA/SLO expectations. |
| AR-006 | Medium | Conflict | Package inventory and architecture examples still assume many standalone shared libraries/bundles, conflicting with the capped internal package policy. | docs/migration/libraries/00-libraries-overview.md:18, docs/migration/libraries/00-libraries-overview.md:32, docs/migration/02-island-boundaries-and-performance.md:58 |
Rewrite library guidance around the 3-package model and clarify what stays island-local vs shared. |
Per-Island Mapping¶
| Island/Area | Status | What Aligns | Main Gaps |
|---|---|---|---|
| Webshop | Partial | Core island boundary is clear. | Wheel-set projection and SLI specification are missing; async write-propagation contract not documented in feature specs. |
| Stock Import | Partial | Separate app and security isolation are explicit. | Connector idempotency, retries, checkpoints, and DLQ policy are not yet documented. |
| Platform Export | Partial | Separate app and platform-specific config are explicit. | Queue classes, checkpointing, replay, and async contract boundaries are underspecified. |
| Vehicle Data | Mostly aligned | Precomputed ProductVehicleMapping aligns with projection-first approach. |
Event publication contract to downstream consumers is not explicit. |
| ERP Middleware | Partial | Dedicated deployable boundary is explicit. | API/event contract and operational SLOs are not documented in migration set. |
| Shared Libraries/Bundles | Conflict | Reuse intent is clear. | Current strategy directly conflicts with capped shared package policy and no-shared-domain-bundle rule. |
| Operations (Cross-Cutting) | Partial | Scheduler contract, locking, and command mapping are detailed. | Outbox/inbox and cross-island event reliability standards are not explicitly attached to scheduler/integration flows. |
Suggested Remediation Sequence¶
- Resolve AR-001 and AR-006 together by replacing bundle strategy docs with the capped package policy.
- Resolve AR-002 by adding a cross-island contracts section (sync + async + outbox/inbox).
- Resolve AR-003 by defining wheel-set projections and refresh triggers in product docs.
- Resolve AR-004 and AR-005 by adding connector and ERP contract deep dives.
Exit Criteria For Next Conformance Pass¶
- All high-severity findings closed in docs.
- Every island overview includes explicit sync and async contract references.
- Webshop product docs include wheel-set projection schema and performance SLI targets.
- Library docs reflect capped shared package policy and remove shared mutable domain bundles.