orion/docs/proposals/SESSION_NOTE_2026-02-09_import002-cross-module-deps.md

Session Note: IMPORT-002 Cross-Module Dependency Cleanup

Date: 2026-02-09 Status: Part A complete, Part B deferred Priority: Medium — architecture cleanup (no runtime crashes, but undeclared dependencies) Follows: SESSION_NOTE_2026-02-03_module-dependency-redesign.md

---

Context

After fixing all IMPORT-001 violations (core → optional) in previous sessions, the architecture validator now passes with 0 errors and 40 IMPORT-002 warnings. These are all optional → optional cross-module imports without declared dependencies.

Billing module is fully clean — zero violations.

---

Current requires=[] Declarations

Module	Currently declares
catalog	requires=["inventory"]
marketplace	requires=["inventory"]
orders	requires=["payments"]
inventory	(nothing)
cart	requires=["inventory"]
analytics	(nothing)

---

Part A: Declare Dependencies (30 warnings — trivial fixes)

These are hard dependencies where the source module fundamentally cannot function without the target. Fix is adding to requires=[] in each module's definition.py.

A1. marketplace → add catalog, orders

Change: requires=["inventory"] → requires=["inventory", "catalog", "orders"] File: app/modules/marketplace/definition.py Warnings resolved: 9

File	Imports from	What
services/marketplace_product_service.py:862-863	catalog	Product model
services/letzshop_export_service.py:16	catalog	Product model
services/letzshop/order_service.py:26-27	catalog, orders	Order, OrderItem, Product models
services/letzshop/order_service.py:17	orders	order_service
services/marketplace_product_service.py:1006	orders	order-related import
routes/api/admin_letzshop.py:23-24	orders	OrderHasUnresolvedExceptionsException, order_item_exception_service
routes/api/store_letzshop.py:24-25	orders	OrderHasUnresolvedExceptionsException, order_item_exception_service

Rationale: Marketplace syncs products and imports orders from Letzshop. No products or orders = no marketplace.

---

A2. orders → add catalog, inventory

Change: requires=["payments"] → requires=["payments", "catalog", "inventory"] File: app/modules/orders/definition.py Warnings resolved: 9

File	Imports from	What
services/order_item_exception_service.py:22,26	catalog	ProductNotFoundException, Product
services/order_service.py:51	catalog	Product model
services/order_inventory_service.py:17-28	inventory	Inventory, InventoryTransaction, TransactionType, exceptions, schemas, service (6 imports)
services/order_service.py:29	inventory	InsufficientInventoryException

Rationale: Order line items reference products. Order fulfillment manages stock via order_inventory_service.py. Both are fundamental.

---

A3. inventory → add catalog

Change: requires=[] → requires=["catalog"] File: app/modules/inventory/definition.py Warnings resolved: 7

File	Imports from	What
services/inventory_service.py:15,33	catalog	ProductNotFoundException, Product
services/inventory_transaction_service.py:14,19	catalog	ProductNotFoundException, Product
services/inventory_import_service.py:27	catalog	Product

Rationale: Every inventory record tracks stock for a product. No products = no inventory.

---

A4. cart → add catalog

Change: requires=["inventory"] → requires=["inventory", "catalog"] File: app/modules/cart/definition.py Warnings resolved: 2

File	Imports from	What
services/cart_service.py:24,27	catalog	ProductNotFoundException, Product

Rationale: Cart items are products. Can't add to cart without the Product model.

---

Part A Subtotal: 4 one-line edits → 27 warnings resolved

(Note: 3 remaining "declare dependency" warnings are covered by marketplace→analytics which is categorized under Part B as provider pattern instead.)

---

Part B: Provider Pattern (10 warnings — moderate refactoring)

These are optional enrichment where the source module works without the target. Need actual refactoring to conditionally load/call.

B1. catalog → marketplace (3 warnings)

File	What
schemas/product.py:14	MarketplaceProductResponse
schemas/catalog.py:14	MarketplaceProductResponse
services/product_service.py:21	MarketplaceProduct model

Why optional: Products exist independently. Marketplace sync status is display enrichment. Fix approach: Make marketplace fields Optional in schemas, populate via provider if marketplace is enabled.

---

B2. marketplace → analytics (2 warnings)

File	What
routes/api/admin_marketplace.py:17	stats_service
routes/api/admin_marketplace.py:29	ImportStatsResponse

Why optional: Marketplace import/sync works without analytics. Stats on admin page are dashboard decoration. Fix approach: Conditionally call stats aggregator, return empty stats if analytics disabled.

---

B3. orders → marketplace (1 warning)

File	What
services/order_service.py:50	MarketplaceProduct, MarketplaceProductTranslation

Why optional: Orders work without marketplace. Enriches order display with Letzshop product info. Fix approach: Conditionally join marketplace data when rendering, skip if module disabled.

---

B4. inventory → orders (2 warnings)

File	What
services/inventory_transaction_service.py:15,18	OrderNotFoundException, Order

Why optional: Inventory tracks stock independently. Order reference on transactions is an audit back-reference, not functional. Fix approach: Store order_id as nullable FK, resolve order details via provider for display.

---

B5. inventory → marketplace (1 warning)

File	What
services/inventory_service.py:606	marketplace import

Why optional: Optional sync enrichment. Fix approach: Conditional import or provider call.

---

B6. analytics → catalog, orders, inventory, marketplace (4 warnings)

File	What
services/stats_service.py:23	Inventory model
services/stats_service.py:24	MarketplaceImportJob, MarketplaceProduct models
services/stats_service.py:25	Order model
services/stats_service.py:26	Product model

Why optional: Analytics aggregates everything — should report on whatever modules are enabled, not crash if one is disabled. Every module already exposes a metrics_provider. Fix approach: Refactor stats_service to use module metrics_provider pattern instead of direct model imports. Cleanest candidate for provider pattern.

---

Part B Subtotal: 6 refactors → 13 warnings resolved

---

Resulting Dependency Tree

After all fixes, the clean module dependency graph:

catalog  (foundational — products)
├── inventory  (requires: catalog)
├── cart  (requires: catalog, inventory)
├── orders  (requires: catalog, inventory, payments)
├── marketplace  (requires: catalog, orders, inventory)
└── analytics  (no hard deps — all via providers)

---

Execution Log

Part A — Completed 2026-02-09

• A1 — marketplace: declare catalog, orders ✅
• A2 — orders: declare catalog, inventory ✅
• A3 — inventory: declare catalog ✅
• A4 — cart: declare catalog ✅

Result: 40 warnings → 13 warnings (27 resolved)

Part B — Deferred (provider pattern refactors)

Remaining 13 warnings require provider pattern refactoring. To be tackled in a future session.

• B6 — analytics: provider pattern (cleanest, biggest impact — 4 warnings)
• B1 — catalog: provider pattern for marketplace enrichment (3 warnings)
• B2 — marketplace: provider pattern for analytics stats (2 warnings)
• B4 — inventory: provider pattern for order back-references (2 warnings)
• B3 — orders: provider pattern for marketplace enrichment (1 warning)
• B5 — inventory: provider pattern for marketplace sync (1 warning)

---

Validation Target

Current state:

$ python scripts/validate/validate_architecture.py
→ 0 errors, 13 warnings (all IMPORT-002 — provider pattern candidates)

After Part B complete:

$ python scripts/validate/validate_architecture.py
→ 0 errors, 0 warnings