# Draft: Framework/Architecture Optimization

## Requirements (confirmed)
- User wants a project-wide review of the current framework/architecture.
- Goal: identify framework-level optimizations to reduce complexity and the need to "jump around" to make changes.
- Concern reported by others: the framework feels "too complex" (likely too many indirections/cross-calls).

## User Preferences (confirmed)
- Focus areas: module layering + dependency injection/service locator complexity.
- Preferred output: a problem list (issues + evidence paths + impact), not a full refactor roadmap (for now).

## Deliverable Format (confirmed)
- Provide: issue list + severity + evidence (paths/call chains). No redesign/implementation proposals in this pass.

## Evaluation Focus (confirmed)
- User wants objective evaluation focused on maintenance cost (readability/changeability/testability).

## Layering Constraint (confirmed)
- Components should be strict UI only: do not touch registry and do not emit global events.
- Components should also NOT directly subscribe/read global theme/locale services; managers should inject theme/locale or push updates.

## Evaluation Criteria (confirmed)
- Evaluate complexity from: readability, changeability, testability, runtime performance, build efficiency.
- Risk tolerance: user is open to large refactors if justified.

## Compatibility Preference (confirmed)
- User is OK with a major-version upgrade and breaking API changes if it yields a simpler SDK facade.

## Multi-instance Requirement (confirmed)
- Must support multiple `BimEngine` instances on the same page, isolated per container.

## Desired Public API UX (confirmed)
- Prefer single-entry, mostly-automatic initialization; internal modules can be lazy/optional.

## Global vs Instance State (confirmed)
- Theme/locale should be global across all viewers on the same page (change once applies to all).

## Event Model (confirmed)
- Events should be isolated per `BimEngine` instance (no implicit cross-instance broadcast).

## Design Constraint (confirmed)
- Keep `ManagerRegistry` as a core design; critique should focus on boundary rules and misuse patterns rather than removing it.

## Registry Model Decision (confirmed)
- User wants to keep `ManagerRegistry` as a global singleton (not per-engine instance).

## Observations (from user)
- "要调来调去" suggests high coupling, too many layers, or hard-to-trace control flow.

## Additional User Context (confirmed)
- User believes current design is intentionally decoupled; wants an objective, fair assessment of where the framework/architecture has problems.
- User is not sure which part is complex; expects reviewer to discover issues by reading the project.

## User Instruction (confirmed)
- User requests reviewer-style assessment without asking many implementation-preference questions.

## Output Artifact
- Audit report drafted at: `.sisyphus/drafts/framework-audit-report.md`.

## Build/Distribution Context (confirmed)
- Built with npm.
- Output is an SDK/library consumed by third-party callers.

## SDK Entry Point (evidence)
- Demo uses UMD global `window.IflowEngine.BimEngine` and instantiates via `new Engine('app', { locale: 'zh-CN' })`.
  - Evidence: `demo/index.html:207-215`, `demo/viewer.html:151-160`.
- Public surface in demo is manager-like properties: `engine.toolbar`, `engine.dialog`, `engine.propertyPanel`, and nested 3D engine access `engine.engine.initialize()` / `engine.engine.loadModel()`.
  - Evidence: `demo/index.html:228-307`, `demo/index.html:343-467`, `demo/index.html:469-478`.

## Primary Distribution Target (confirmed)
- Primary consumption: ESM `import { BimEngine } from 'iflow-engine'`.

## Early Code Findings (evidence; subject to deeper review)
- `BimEngine` currently *eagerly constructs* many managers inside its constructor flow (`this.init()`), rather than requiring external `initX()` calls.
  - Evidence: `src/bim-engine.ts:46-69`, `src/bim-engine.ts:95-142`.
- There is a singleton-style registry/service-locator (`ManagerRegistry.getInstance()`), and `BimEngine` writes many manager references into it.
  - Evidence: `src/bim-engine.ts:57-58`, `src/bim-engine.ts:101-136`.
- This creates a potential mismatch with docs that describe “user calls initEngine()/initToolbar()/...” as a step-by-step initialization.
  - Evidence: `README.md` “快速开始/初始化各个管理器” section vs `src/bim-engine.ts` eager init.
- Build is Vite library mode, with `inlineDynamicImports: true` (single-file bundle), which can reduce ESM tree-shaking benefits and may increase load size.
  - Evidence: `vite.config.ts:26-38`, `package.json:5-13`.

## Doc Findings (evidence)
- Architecture docs explicitly define `ManagerRegistry` as Singleton + Service Locator, and many call chains obtain it via `ManagerRegistry.getInstance()` even in leaf button configs.
  - Evidence: `docs/架构设计.md:100-115`, `docs/API调用链.md:69-93`.
- Call-chain doc shows deep 5-layer pipeline (Button -> DialogManager -> EngineManager -> Engine component -> base engine). This is understandable but can feel "too many hops" when changes span layers.
  - Evidence: `docs/API调用链.md:714-748`.
- Core docs show `ManagerRegistry` stores `container/wrapper` plus many manager instances, making it effectively a global mutable bag of state.
  - Evidence: `docs/MODULES/核心模块.md:114-137`.

## Technical Decisions
- TBD

## Research Findings
- Pending codebase exploration.

## Scope Boundaries
- INCLUDE: architecture review, module boundaries, dependency direction, layering, wiring/DI, config/initialization flow, build/runtime structure.
- EXCLUDE: feature work unless explicitly requested; large refactor without a plan.

## Open Questions
- What does "framework" refer to here (backend framework / engine core architecture / plugin system / build system)?
- What are the top pain points (debugging, onboarding, adding features, runtime performance, build speed)?
- What constraints exist (API stability, deadlines, must-keep patterns, target platforms)?