Architectural Decisions - Refreshed November 2025

Updated decisions matrix for modular-universe, space-map, and widget/module taxonomy

✅ Architectural Decisions - Refreshed November 2025

Last Updated: November 14, 2025
Status: 🎯 ACTIVE DECISIONS
Purpose: Definitive record of architectural decisions after deep platform analysis

🎯 EXECUTIVE SUMMARY

After comprehensive analysis of the current platform state, we have confirmed and refined critical architectural decisions that will guide development forward.

Key Insight: The previous CRITICAL-DECISIONS-REQUIRED.md was partially outdated. Many decisions have already been implemented, while others require refinement based on current platform capabilities.

📋 DECISION MATRIX

Decision 1: Space-Map vs Modular-Universe ✅ CONFIRMED

Original Question: Fix space-map or replace with modular-universe?

DECISION: DUAL-TRACK APPROACH ⭐

Rationale:

space-map-lib (libs/libs-structural/space-map-lib/) has existing routes and components that serve legacy universe/galaxy/world navigation
modular-universe (libs/libs-structural/modular-universe/) represents the next-generation grid-based builder with advanced capabilities
Both serve different but complementary purposes in the platform

Implementation Strategy:

TRACK 1: space-map-lib (Legacy/Navigation)
Purpose: Universe navigation, detail views, analytics
Status: Maintain and enhance gradually
Routes: /space/:spaceSlug/space-map/* (existing)
Components:
  - space-overview.component.ts
  - universe-detail.component.ts
  - galaxy-detail.component.ts
  - world-detail.component.ts
  - universe-analytics.component.ts

TRACK 2: modular-universe (Builder/Grid)
Purpose: Visual grid-based universe/galaxy construction
Status: Continue rapid development (primary focus)
Routes: /space/:spaceSlug/modular-universe/* (new)
Components:
  - modular-universe-builder.component.ts
  - grid-canvas.component.ts
  - section-config-panel.component.ts
  - module-connection-system.component.ts

Integration Points:

space-map links to modular-universe for "Edit Structure" actions
modular-universe saves layouts that space-map navigates/displays
Both consume UniversalModuleService for module data
Both use @storage-system for persistence

Migration Path:

Phase 1: Keep both operational (CURRENT)
Phase 2: Enhance modular-universe to feature parity (Q1 2026)
Phase 3: Redirect primary creation flows to modular-universe (Q2 2026)
Phase 4: Deprecate space-map OR transform into analytics/reporting tool (Q3 2026)

Status: ✅ IMPLEMENTED - Both libraries active and complementary

Decision 2: UI Builder Restructure ✅ OPTION A CONFIRMED

Original Question: Showcase vs Widget Builder vs Deprecate?

DECISION: SPLIT INTO TWO LIBRARIES (OPTION A) ⭐

Implementation:

CURRENT:
libs/libs-ui/ui-builder/ (Mixed purpose, broken routes)

SPLIT INTO:

1. libs/libs-ui/widget-showcase/
   Purpose: Documentation and showcase of existing widgets
   Features:
     - Interactive examples
     - Code snippets
     - Visual variant selector
     - Theme integration examples
   Routes: /space/:spaceSlug/widgets/showcase
   Status: TO BE CREATED

2. libs/libs-structural/widget-builder/
   Purpose: Visual tool to CREATE new widgets
   Features:
     - Visual widget composer
     - Property/IO panel
     - Variant creator
     - Live preview
     - Export as component
   Routes: /space/:spaceSlug/widgets/builder
   Status: TO BE CREATED

3. Theme Components → libs/theme-system/theme-components/
   Purpose: Theme-specific UI components
   Status: TO BE MIGRATED

Rationale:

Clear separation of concerns (showcase vs creation)
Aligns with platform philosophy (tools that build tools)
Theme components belong with theme system
Fixes routing issues by fresh start

Status: ⏳ PENDING IMPLEMENTATION - Documented and approved

Decision 3: Widget vs Module Boundary 🆕 HYBRID APPROACH

Original Question: Which elements should stay as widgets vs become modules?

DECISION: FUNCTIONAL PROGRESSION MODEL ⭐

Core Principle:

Widget (Pure UI) + Functionality (Flows/Logic) = Module (Reusable System)

Decision Matrix:

Component Type	Classification	When to Promote	Example
Input Fields	Widget	When bound to flows/validation	`<gg-input>` → `user-input-module` (with validation flow)
Select Dropdowns	Widget	When managing complex data sources	`<gg-select>` → `data-select-module` (with API flow)
Buttons	Widget	When triggering multi-step flows	`<gg-button>` → `action-button-module` (with flow)
Cards	Widget	When containing modules	`<gg-card>` → `content-card-module`
Modals	Module (always)	Immediate	Complex lifecycle + state
Sidebars	Module (always)	Immediate	Navigation + state management
Navigation	Module (always)	Immediate	Routing + state
Data Grids	Module (always)	Immediate	State + pagination + sorting
Forms (simple)	Widget	When validation/submission added	`<gg-form>` → `smart-form-module`
Forms (complex)	Module (always)	Immediate	Multi-step + business logic

Promotion Criteria:

A widget should be promoted to a module when it gains ANY of:

✅ Singularity Integration - Attached to logic blocks or flows
✅ Lifecycle Management - Needs onInit/onDestroy hooks with business logic
✅ State Management - Complex internal state beyond UI
✅ Routing - Has its own routes or navigation
✅ Children Management - Contains other modules
✅ Backend Integration - Direct API calls beyond simple data binding

Implementation Guidelines:

// WIDGET: Pure UI with @Input/@Output
@Component({
  selector: 'gg-input',
  standalone: true,
  inputs: ['value', 'placeholder', 'disabled'],
  outputs: ['valueChange', 'blur', 'focus']
})
export class GgInputWidget {
  // Pure presentation, no business logic
}

// MODULE: Widget + Functionality
@Component({
  selector: 'gg-smart-input',
  standalone: true
})
export class SmartInputModule implements BrowserModuleContract {
  readonly manifest: ModuleManifest = {
    id: 'smart-input',
    name: 'Smart Input',
    actions: ['validate', 'transform', 'submit'],
    flows: ['validation-flow', 'submission-flow']
  };
  
  // Business logic, flow integration, validation
  async validate() { /* ... */ }
  async submit() { /* ... */ }
}

Storage Strategy:

Widgets: Stored in libs/libs-ui/ or libs/widgets/
Promoted Modules: Stored in libs/libs-structural/ or libs/libs-module-features/
Manifest Registration: Only modules register with ModuleRegistryService

Status: ✅ DOCUMENTED - Ready for implementation

Decision 4: Grid vs Flexbox Strategy ✅ ALREADY IMPLEMENTED

Original Question: CSS Grid only, Flexbox only, or both?

DECISION: HYBRID - BOTH IMPLEMENTED ⭐

Current Implementation:

// Already implemented in grid-canvas.component.ts
interface LayoutConfiguration {
  type: 'flexbox' | 'grid';
  
  flexbox?: {
    direction: 'row' | 'column';
    wrap: 'nowrap' | 'wrap';
    justifyContent: string;
    alignItems: string;
    gap: string;
  };
  
  grid?: {
    rows: string[];
    columns: string[];
    gap: string;
  };
  
  sections: SectionConfig[];
}

Features Implemented:

✅ Flexbox mode (default): layoutConfig.type = 'flexbox'
✅ CSS Grid mode: layoutConfig.type = 'grid'
✅ Dynamic switching: switchLayoutType(type: LayoutType)
✅ Section-level config for both modes
✅ Responsive controls
✅ Storage persistence

Platform Export:

Web: Uses native CSS Grid/Flexbox
Mobile (Future): Generate Flexbox equivalent automatically
Storage: Both representations stored in module config

Status: ✅ FULLY IMPLEMENTED - Working and tested

Decision 5: Canvas Cutting Mechanic ✅ PARTIALLY IMPLEMENTED

Original Question: Divider lines vs drag-to-split vs templates?

DECISION: TOOLBAR + MODE SYSTEM (IMPLEMENTED) ⭐

Current Implementation:

// Mode system implemented in grid-canvas.component.ts
type CanvasMode = 'select' | 'add' | 'resize' | 'reorder';

// Current features:
- ✅ Mode toolbar
- ✅ Add section mode
- ✅ Resize mode with handles
- ✅ Reorder mode with drag-drop
- ✅ Select mode for configuration

What's Implemented:

✅ Canvas modes (select, add, resize, reorder)
✅ Section creation (addSection method)
✅ Section resizing (startResize, resizeSection methods)
✅ Section reordering (drag-drop with CDK)
✅ Section configuration panel integration

What's Needed (Cutting Mechanic Vision):

⏳ Visual divider lines (draggable horizontal/vertical)
⏳ Canvas "cutting" UX (drag dividers to slice)
⏳ Auto-section generation from divider positions
⏳ Template presets (header/content/footer, sidebar layouts)

Enhancement Strategy:

// Proposed addition:
type CanvasMode = 'select' | 'add' | 'resize' | 'reorder' | 'divide';

// New features:
- Add 'divide' mode
- Draggable divider lines (horizontal/vertical)
- On confirm: Calculate sections from divider positions
- Generate CSS Grid from dividers
- Each section auto-becomes sub-module

Status: ✅ FOUNDATION IMPLEMENTED - Needs cutting mechanic enhancement

🏗️ ARCHITECTURE ALIGNMENT

Current Platform State

Working Systems:

✅ Universal Module System - UniversalModuleService operational
✅ Module Registry - ModuleRegistryService with manifests
✅ Storage System - Flash persistence + backend sync
✅ Grid Canvas - Flexbox/Grid builder working
✅ Section Configuration - Tabbed panel with module browser
✅ Theme System - CSS variables, modern design
✅ Module Browser - Visual selection with access control

Libraries Status:

Library	Location	Status	Purpose
modular-universe	`libs/libs-structural/`	✅ Active Development	Grid-based builder (PRIMARY)
space-map	`libs/libs-structural/`	✅ Maintained	Navigation/analytics (LEGACY)
singularity	`libs/libs-structural/`	✅ Operational	Logic blocks + flows
editor-web-lib	`libs/libs-structural/`	✅ Operational	Page editor
modularity-lib	`libs/libs-structural/`	✅ Needs Enhancement	Module creation wizard
ui-builder	`libs/libs-ui/`	⚠️ Broken Routes	Needs split (Decision 2)
widget-showcase	-	⏳ To Create	Showcase library
widget-builder	-	⏳ To Create	Creation tool

🔄 INTEGRATION STRATEGY

How Components Work Together

┌─────────────────────────────────────────────────────────────┐
│ SPACE BUILDER WORKFLOW                                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│ 1. CREATE UNIVERSE (Dashboard)                              │
│    ↓                                                         │
│ 2. STRUCTURE GRID (modular-universe)                        │
│    - Define layout (flexbox/grid)                           │
│    - Add/resize/reorder sections                            │
│    - Each section = sub-module                              │
│    ↓                                                         │
│ 3. ASSIGN CONTENT (section-config-panel)                    │
│    - Browse modules (module-browser)                        │
│    - Assign to sections                                     │
│    - Configure behaviors                                    │
│    ↓                                                         │
│ 4. BUILD PAGES (editor-web-lib)                             │
│    - Visual page editor                                     │
│    - Widget placement                                       │
│    - Content management                                     │
│    ↓                                                         │
│ 5. ADD LOGIC (singularity)                                  │
│    - Create logic blocks                                    │
│    - Build flows                                            │
│    - Attach to modules/widgets                              │
│    ↓                                                         │
│ 6. CREATE MODULES (modularity-lib)                          │
│    - Package reusable modules                               │
│    - Configure manifests                                    │
│    - Export for reuse                                       │
│    ↓                                                         │
│ 7. PREVIEW (launch-station)                                 │
│    - Test universe                                          │
│    - Device preview                                         │
│    - Quality check                                          │
│    ↓                                                         │
│ 8. DEPLOY (launch-station)                                  │
│    - Deploy to production                                   │
│    - Configure domain                                       │
│    - Go live                                                │
│    ↓                                                         │
│ 9. MANAGE (space-management)                                │
│    - Monitor deployed universe                              │
│    - View analytics                                         │
│    - Manage data                                            │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Module Communication Flow

// Storage Layer
@storage-system (flash-persistence + backend)
  ↓
// Service Layer
UniversalModuleService (CRUD operations)
ModuleRegistryService (manifests)
  ↓
// Component Layer
modular-universe-builder → grid-canvas → section-config-panel
  ↓                            ↓              ↓
space-map (navigation)    editor-web    singularity
  ↓
// Output Layer
launch-station (preview/deploy)
space-management (analytics)

📊 IMPLEMENTATION PRIORITY

Phase 1: Foundation (Weeks 1-2) ✅ MOSTLY COMPLETE

Universal module system
Grid canvas with flexbox/grid
Section configuration panel
Module browser integration
Storage system integration
Documentation updates (IN PROGRESS)

Phase 2: Builders (Weeks 3-4) ⏳ NEXT

Split ui-builder → widget-showcase + widget-builder
Fix broken routes
Enhance modularity-lib creation flows
Improve singularity integration
Editor-web module assignment

Phase 3: Cutting Mechanic (Weeks 5-6) 📋 PLANNED

Add 'divide' mode to canvas
Draggable divider lines
Auto-section generation
Template presets
Enhanced UX

Phase 4: Integration (Weeks 7-8) 📋 PLANNED

Connect all tools seamlessly
Preview pipeline
Deployment workflow
Analytics/management

Phase 5: Polish (Weeks 9-12) 📋 FUTURE

AI-powered features
Advanced collaboration
Marketplace preparation
Performance optimization

🎯 SUCCESS CRITERIA

Technical

✅ Dual-track architecture (space-map + modular-universe)
✅ Hybrid layout system (flexbox + grid)
✅ Widget/module progression model defined
⏳ All routes functional
⏳ Seamless tool integration

User Experience

✅ Beautiful, clean interface
✅ Intuitive grid building
⏳ Smooth workflows (create → build → deploy)
⏳ Zero-training for basic tasks
⏳ Advanced features for power users

Platform Goals

✅ Everything is a module
✅ Modules build modules
⏳ AI-trainable architecture
⏳ Platform-agnostic export
⏳ Marketplace ready

📚 RELATED DOCUMENTS

Master Plan: ULTIMATE-PLATFORM-BUILDER-MASTER-PLAN.md
Progress: progress.md
Next Steps: next-steps.md
Module System: BREAKTHROUGH-MODULES-ARE-STRUCTURE.md
Architecture: ARCHITECTURE-STATUS-COMPLETE.md
Original Decisions: CRITICAL-DECISIONS-REQUIRED.md (outdated, superseded by this doc)

Status: ✅ DECISIONS CONFIRMED
Next Action: Proceed with Phase 2 implementation
Owner: Development Team
Last Updated: November 14, 2025