Skip to content

9. Architecture Decisions (MVP)

9.1 MVP Architecture Decisions Overview

MVP ADR Status

ADR Title Status Impact
ADR-001 Hexagonal Pipeline Architecture ✅ Accepted Clean separation of concerns
ADR-002 4-Layer Validation Framework ✅ Accepted Comprehensive input validation
ADR-003 Field Name Standardization ✅ Accepted Consistent naming conventions
ADR-004 4 Bounded Context Architecture ✅ Accepted Domain separation (updated to 4 contexts)
ADR-005 Type Hints Mandatory ✅ Accepted Code quality and safety
ADR-006 SimPy for Discrete Event Simulation ✅ Accepted Proven simulation framework
ADR-007 File-Based Data Storage ✅ Accepted Simple deployment
ADR-008 Pydantic for Data Validation ✅ Accepted Type safety and validation
ADR-009 Matplotlib for Visualization ✅ Accepted Simple offline charts
ADR-010 Layered Architecture ✅ Accepted Rapid development
ADR-011 4 Bounded Contexts ✅ Accepted Minimal viable domain decomposition (updated to 4 contexts)
ADR-012 Direct Method Calls ✅ Accepted Simple integration
ADR-013 Hexagonal Architecture for Data Sources ✅ Accepted Multi-format input support
ADR-014 Wagon Tracking and Queue Management ✅ Implemented Resolved wagon tracking issues
ADR-015 SimPy Workshop Modeling ✅ Implemented Complete SimPy integration
ADR-016 Capacity Management Integration ✅ Implemented Physical capacity validation

Note: Full version architectural decisions (ADR-001 through ADR-013) are documented in ../../full-version/architecture/decisions/.

9.2 MVP Architecture Decisions

All MVP architectural decisions are documented as separate ADR files in the decisions directory. This section provides an overview and links to the detailed decisions.

Architecture Pattern Decisions

Technology Decisions

Quality & Standards Decisions

Integration Decisions

Implementation Decisions (Resolved Issues)

Implementation: - DataSourcePort: Interface defining adapter contract - JsonDataSourceAdapter: Wraps existing JSON functionality - CsvDataSourceAdapter: New CSV directory support - DataSourceFactory: Auto-detects source type - ScenarioLoader: Orchestrates using adapters

Alternatives Considered: - Hexagonal Architecture ✅ Chosen - Direct CSV parsing: Tight coupling, hard to test - Single JSON format: Doesn't meet CSV requirement - Full hexagonal everywhere: Too complex for MVP timeline

Consequences: - Positive: Multi-format support, future-ready, testable, maintainable - Negative: Additional complexity (justified by requirements) - Benefit: Foundation for full hexagonal architecture migration

CSV Directory Structure: 

csv_scenario/
├── scenario.csv      # Basic metadata (ID, dates, seed)
├── trains.csv        # Train schedule with arrival times
├── wagons.csv        # Wagon data linked to trains
├── workshops.csv     # Workshop configuration
├── tracks.csv        # Track definitions
├── routes.csv        # Route definitions
└── locomotives.csv   # Locomotive fleet data

Usage Examples: 

# Auto-detect source type
loader = ScenarioLoader()
scenario = loader.load_scenario('path/to/csv_directory')  # CSV
scenario = loader.load_scenario('path/to/scenario.json')  # JSON

# Use specific adapter
csv_adapter = CsvDataSourceAdapter()
scenario = csv_adapter.load_scenario('csv_directory')

9.3 Rejected Alternatives

Rejected Architecture Options

Alternative Reason for Rejection MVP Decision
Hexagonal Architecture Too complex for 5-week timeline Layered Architecture
Microservices Deployment complexity Monolith
Event-driven Implementation effort Direct calls
Web Frontend No frontend developer Matplotlib
Database Installation complexity Files

Rejected Technology Options

Technology Reason for Rejection MVP Alternative
FastAPI Web API not required Direct Python calls
PostgreSQL Database setup too complex CSV/JSON files
Docker Container overhead Native Python
Vue.js Frontend development Matplotlib PNG
WebSocket Real-time not required Batch processing

9.4 Migration Path

MVP → Full Version Evolution

Aspect MVP (Current) Transition (Prepared) Full Version (Future)
Architecture Layered within contexts Interface preparation Hexagonal architecture
Integration Direct method calls + Event bus Repository pattern Event-driven
Storage File-based (JSON/CSV) Repository abstraction Database + Event Store
Visualization Matplotlib (PNG) JSON data export Web frontend (interactive)
Contexts 4 bounded contexts Interface boundaries Multiple contexts (TBD)
Deployment Desktop application Containerization prep Cloud-ready web app

Migration Strategy: - MVP decisions prioritize rapid development (5-week timeline) - Transition preparations embedded in MVP (repository pattern, interfaces) - Full version evolution planned but not blocking MVP delivery