🏗️ Architecture: How should Platform Elements runtime be structured for maint...

Date: 2026-03-25
Time: 18:10:13 UTC
Session: gspace1-269.2
Agent: architecture
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should Platform Elements runtime be structured for maintainability and AI-agent friendliness?

Task: Not specified

🎯 Decision Made

Chosen:

Split 4 monolithic files (expression-engine 336L, expression-bindings 255L, action-dispatcher 282L, element-inspector 205L) into 14 focused sub-modules organized by concern: expression/ (tokenizer, parser with AST, evaluator), actions/ (parser, executor, click-handler, response-handler-registry), bindings/ (pe-attribute-handlers, wizard-step-navigator), inspector/ (element-detector, highlight-renderer, studio-bridge). Plus 3 shared utilities: constants.ts (all magic strings), global-contracts.ts (typed window accessors), field-value-extractor.ts (shared form value read/write).

Options Considered:

• No alternatives documented

💭 Reasoning

Audited all 11 runtime files against Global Engineering Standard. Found 4 files with CRITICAL violations: mixed responsibilities, god methods (>30 lines), duplicated field extraction logic across 3 files, 60+ hardcoded magic strings, and implicit window global contracts. The expression engine mixed tokenization+parsing+evaluation in one class — separating into AST-based architecture enables caching, debugging, and validation. Response handlers used a 73-line switch statement — registry map pattern makes it discoverable and extensible. Field value extraction was copy-pasted in 3 files — single utility eliminates drift.

📁 Files Involved

• libs/libs-structural/platform-elements/src/lib/runtime/constants.ts
• libs/libs-structural/platform-elements/src/lib/runtime/global-contracts.ts
• libs/libs-structural/platform-elements/src/lib/runtime/field-value-extractor.ts
• libs/libs-structural/platform-elements/src/lib/runtime/expression/expression-tokenizer.ts
• libs/libs-structural/platform-elements/src/lib/runtime/expression/expression-parser.ts
• libs/libs-structural/platform-elements/src/lib/runtime/expression/expression-evaluator.ts
• libs/libs-structural/platform-elements/src/lib/runtime/actions/action-parser.ts
• libs/libs-structural/platform-elements/src/lib/runtime/actions/action-executor.ts
• libs/libs-structural/platform-elements/src/lib/runtime/actions/action-click-handler.ts
• libs/libs-structural/platform-elements/src/lib/runtime/actions/response-handler-registry.ts
• libs/libs-structural/platform-elements/src/lib/runtime/bindings/pe-attribute-handlers.ts
• libs/libs-structural/platform-elements/src/lib/runtime/bindings/wizard-step-navigator.ts
• libs/libs-structural/platform-elements/src/lib/runtime/inspector/element-detector.ts
• libs/libs-structural/platform-elements/src/lib/runtime/inspector/highlight-renderer.ts
• libs/libs-structural/platform-elements/src/lib/runtime/inspector/studio-bridge.ts

🔗 Related

• Decision ID: dev_1774462213635_syp146s
• Session: 269
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation