9. Architekturentscheidungen

Wichtige, teure, große oder riskante Architektur- oder Entwurfsentscheidungen inklusive der jeweiligen Begründungen. Mit "Entscheidungen" meinen wir hier die Auswahl einer von mehreren Alternativen unter vorgegebenen Kriterien.

Alle Architekturentscheidungen für den Wardley Map Editor sind als Architecture Decision Records (ADRs) dokumentiert. Diese wurden während der Live-Session basierend auf unserem 1-Stunden Zeitbudget getroffen.

Übersicht der Entscheidungen

ADR Entscheidung Begründung

ADR-001

SVG für Rendering (vs. Canvas)

Einfacheres Event-Handling, besseres Debugging

ADR-002

Simple Event Handlers (vs. MVC/Frameworks)

Minimaler Boilerplate, schnelle Implementierung

ADR-003

LocalStorage (vs. IndexedDB/No Persistence)

Einfache API, ausreichend für Demo-Scope

ADR-004

Mouse-Only Interaction (vs. Touch/Keyboard)

Reduzierte Komplexität, Desktop-Demo fokussiert

Architecture Decision Records

ADR-001: Rendering Technology Selection - SVG for Wardley Map Visualization

Date:

2025-06-13

Authors:

Ralf D. Müller, Claude (AI Assistant)

Status:

Final

Problem Description and Context

We need to select a rendering technology for the Wardley Map Editor that allows: - Visual representation of map components (rectangles) - Interactive drag & drop functionality - Line drawing for dependencies - Export to draw.io XML format

The decision must be made within our 1-hour live-stream timeframe, requiring a technology that can be implemented quickly while providing good user experience.

Alternative Evaluation (Pugh Matrix)

Criterion

Canvas (Baseline)

SVG

Implementation Speed

0

+1

Event Handling Complexity

0

+1

Performance (Small Scale)

0

0

Code Maintainability

0

+1

Debugging Capabilities

0

+1

Learning Curve

0

+1

Total Score

0

+5

Rejected Alternatives:

Canvas: While Canvas offers superior performance for large-scale applications (1000+ elements), it requires: - Manual implementation of hit-testing for mouse events - Custom coordinate transformation logic - More complex drag & drop implementation - No direct DOM inspection capabilities

For our demo scope (10-20 components max), Canvas’s performance advantages are not needed, while its complexity would consume valuable implementation time.

Decision

We choose SVG for rendering the Wardley Map visualization.

Rationale: - Time Efficiency: DOM-based event handling reduces implementation complexity - Demo Suitability: Elements are directly inspectable in browser dev tools - Sufficient Performance: SVG handles our target scale (10-20 components) without issues - Coordinate Simplicity: Direct pixel coordinates, no transformation matrices needed - CSS Integration: Styling can be handled through CSS classes

Consequences

Positive Effects

  • Faster Development: Reduced implementation time for interactive features

  • Better Debugging: All map elements visible in DOM inspector during live demo

  • Simpler Codebase: Less boilerplate code for basic functionality

  • CSS Styling: Standard web technologies for visual customization

Risks

  • Performance Ceiling: May not scale beyond 100+ components (not relevant for demo)

  • Animation Limitations: Complex animations less smooth than Canvas (not planned)

Technical Debt

None. The decision aligns with our demo scope and requirements. Performance limitations and animation constraints are not relevant for our intended use case of 10-20 components in a live demo context.

Implementation Notes

SVG Structure for Wardley Maps:

<svg viewBox="0 0 1200 800">
  <!-- Axes -->
  <line x1="100" y1="700" x2="1100" y2="700" /> <!-- Evolution -->
  <line x1="100" y1="100" x2="100" y2="700" />   <!-- Value -->

  <!-- Components -->
  <rect id="comp1" x="200" y="300" width="100" height="40" />
  <text x="250" y="325">User Needs</text>

  <!-- Dependencies -->
  <line x1="250" y1="340" x2="350" y2="450" />
</svg>

Event Handling:

component.addEventListener('mousedown', startDrag);
component.addEventListener('mousemove', drag);
component.addEventListener('mouseup', endDrag);

ADR-002: Architecture Pattern Selection - Simple Event Handlers

Date:

2025-06-13

Authors:

Ralf D. Müller, Claude (AI Assistant)

Status:

Final

Problem Description and Context

We need to choose an architecture pattern for organizing the Wardley Map Editor code. The solution must be implementable within 25 minutes while providing clean separation of concerns for: - User interface interactions - Data management - Rendering logic - Export functionality

Alternative Evaluation (Pugh Matrix)

Criterion

Simple Event Handlers (Baseline)

MVC Pattern

Component Architecture

Implementation Speed

0

-2

-2

Code Complexity

0

-1

-2

Maintainability

0

+1

+2

Learning Curve

0

-1

-2

Demo Suitability

0

-1

-1

Total Score

0

-4

-5

Rejected Alternatives:

MVC Pattern: Would require separate Model, View, Controller classes and event bus implementation - too much boilerplate for 25-minute implementation.

Component Architecture: Modern but requires careful design of component interfaces and lifecycle management - complexity not justified for demo scope.

Decision

We choose Simple Event Handlers with direct DOM manipulation.

Rationale: - Minimal Boilerplate: Direct addEventListener() calls, no framework overhead - Fast Implementation: Straightforward JavaScript without architectural complexity - Easy Debugging: Clear event flow, no hidden abstractions - Demo Focus: Code remains readable and explainable during live stream

Consequences

Positive Effects

  • Rapid Development: Minimal setup, direct implementation

  • Clear Code Flow: Easy to follow during live demonstration

  • No Dependencies: Pure JavaScript, no architectural libraries needed

Risks

  • Code Organization: May become messy if scope grows beyond demo

  • Event Management: Manual event cleanup required

Technical Debt

None. Simple event handlers are appropriate for our demo scope and timeline.

ADR-003: Data Persistence Strategy - LocalStorage Only

Date:

2025-06-13

Authors:

Ralf D. Müller, Claude (AI Assistant)

Status:

Final

Problem Description and Context

We need to decide how to persist Wardley Map data between browser sessions. The solution must work without server infrastructure and be implementable within our time constraints.

Alternative Evaluation (Pugh Matrix)

Criterion

LocalStorage (Baseline)

IndexedDB

No Persistence

Implementation Speed

0

-2

+1

Data Capacity

0

+1

-2

Browser Support

0

-1

+1

API Complexity

0

-2

+1

Demo Value

0

0

-2

Total Score

0

-4

-1

Rejected Alternatives:

IndexedDB: More powerful but asynchronous API adds complexity. 5-10MB capacity not needed for demo maps.

No Persistence: Would frustrate demo users who lose work on page refresh.

Decision

We choose LocalStorage for map data persistence.

Rationale: - Simple API: Synchronous JSON.stringify/parse operations - Sufficient Capacity: 5MB limit more than adequate for demo maps - Universal Support: Available in all target browsers - Immediate Implementation: No complex async handling required

Consequences

Positive Effects

  • Fast Implementation: Simple key-value storage, no complex data modeling

  • User Experience: Maps persist across browser sessions

  • No Infrastructure: Client-side only, no server dependencies

Risks

  • Storage Limits: 5MB browser limit (not relevant for demo scope)

  • Browser Clearing: Data lost if user clears browser storage (acceptable for demo)

Technical Debt

None. LocalStorage meets all demo requirements without over-engineering.

Implementation Notes

Data Structure:

const mapData = {
  id: crypto.randomUUID(),
  title: "My Wardley Map",
  components: [
    {id: "comp1", label: "User Needs", x: 0.2, y: 0.9}
  ],
  dependencies: [
    {from: "comp1", to: "comp2"}
  ],
  lastModified: new Date().toISOString()
};

localStorage.setItem('wardley-map', JSON.stringify(mapData));

ADR-004: User Interface Strategy - Mouse-Only Interaction

Date:

2025-06-13

Authors:

Ralf D. Müller, Claude (AI Assistant)

Status:

Final

Problem Description and Context

We need to define the user interaction model for the Wardley Map Editor. The solution must be implementable within our remaining 20 minutes while providing intuitive map editing capabilities.

Alternative Evaluation (Pugh Matrix)

Criterion

Mouse-Only (Baseline)

Touch Support

Keyboard Shortcuts

Implementation Speed

0

-2

-1

Code Complexity

0

-2

-1

Browser Testing

0

-2

0

Demo Focus

0

-1

-1

User Experience

0

+1

+1

Total Score

0

-6

-2

Rejected Alternatives:

Touch Support: Requires handling touchstart/touchmove/touchend events with different coordinate systems. Additional complexity for device testing.

Keyboard Shortcuts: Would require key binding management and user documentation. Not essential for basic demo functionality.

Decision

We choose Mouse-Only interaction for the initial implementation.

Rationale: - Time Efficiency: Single event model (mousedown/mousemove/mouseup) - Demo Environment: Live stream likely uses desktop browser - Testing Simplicity: No cross-device testing required - Clear Implementation: Straightforward drag & drop implementation

Consequences

Positive Effects

  • Rapid Development: Single interaction model to implement

  • Predictable Behavior: Consistent mouse event handling across browsers

  • Easy Debugging: Clear event flow for live demonstration

Risks

  • Limited Accessibility: No keyboard navigation support

  • Mobile Limitation: Not usable on touch devices

Technical Debt

Minor. Touch support could be added later with minimal refactoring by extending existing mouse event handlers.

Implementation Notes

Event Handling:

// Component drag & drop
component.addEventListener('mousedown', startDrag);
document.addEventListener('mousemove', drag);
document.addEventListener('mouseup', endDrag);

// Canvas click for new components
canvas.addEventListener('click', addComponent);

Coordinate Handling:

function getMousePosition(event, svg) {
  const rect = svg.getBoundingClientRect();
  return {
    x: event.clientX - rect.left,
    y: event.clientY - rect.top
  };
}