Initiative: 1: Core Architecture Modernization & Concurrency Hardening

[fderuiter]

Epic: Core Architecture Modernization & Concurrency Hardening

Labels: epic, architecture, tech-debt
Status: In Progress

📖 Context & Background

As the imednet-python-sdk scales to support multi-threaded orchestration tools (like Apache Airflow) and complex UI plugins (like Streamlit dashboards), our foundational architecture must be bulletproof.

Currently, the SDK suffers from a monolithic structure, legacy Mixin patterns, and critical concurrency hazards involving shared mutable state. This Epic tracks the comprehensive refactoring required to transition the SDK into a stateless, composition-based, multi-package workspace.

🎯 Epic Objectives

1. Zero Data Leaks: Eradicate global state to make the SDK 100% thread-safe and async-safe.
2. Strict Package Isolation: Decouple opinionated workflows and CLI logic from the lightweight API client.
3. Forward Compatibility: Ensure Pydantic models gracefully handle unannounced upstream API additions.
4. Developer Experience: Replace opaque Mixin inheritance with flat, explicit Composition.

---

🛤️ Execution Plan & Ticket Tracking

Note: Tickets are grouped by phase. A phase must be completed and merged before work begins on the next phase.

Phase 1: Critical Production Blockers 🚨

These issues pose a direct threat to runtime stability and data integrity. They must be resolved immediately.

• 1 The Stateful Client Anti-Pattern (Concurrency Hazard) #912: The Stateful Client Anti-Pattern (Concurrency Hazard)
• 2 Pydantic Strictness in Third-Party APIs #875: Pydantic Strictness in Third-Party APIs

Phase 2: Architectural Foundations 🧱

These tickets resolve deep architectural debts that block safe scaling. We must split the monolith before adding new plugins.

• 3 Architectural Scope Creep (Monolith vs. Workspace) #914: Architectural Scope Creep (Monolith vs. Workspace)
• 4 Brittle URL Path Construction #876: Brittle URL Path Construction
• (Placeholder) Feature: Reporting Dashboard #915: Feature: Reporting Dashboard (Streamlit Plugin) — Blocked until 3 Architectural Scope Creep (Monolith vs. Workspace) #914 is merged.

Phase 3: Maintainability & Developer Experience 🛠️

These issues affect the developers maintaining the SDK and the end-user IDE experience.

• 5 Incomplete Migration: Mixins to Composition #913: Incomplete Migration: Mixins to Composition
• 6 CLI Coupling #871: CLI Coupling (Moving output logic out of core)
• 7 Interface Ambiguity and Type Degradation #873: Interface Ambiguity and Type Degradation (Strict Protocols)

---

🛑 Definition of Done (DoD) for Epic

• All sub-issues linked above are closed.
• The repository physically utilizes a packages/ directory with isolated pyproject.toml files.
• pytest suites for concurrency and state isolation pass with 100% reliability.
• A minor release (e.g., v0.6.0) is cut containing these breaking structural changes, complete with a migration guide for existing users.

---