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 Multi-layer input validation
ADR-003 Field Name Standardization Accepted Consistent naming conventions
ADR-004 3-Bounded Context Architecture Superseded Original 3-context split; replaced by the 4-context model
ADR-005 Type Hints Mandatory Accepted Code quality and safety
ADR-006 SimPy for Discrete Event Simulation Accepted Discrete-event 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 Superseded Replaced by Streamlit + Plotly dashboard
ADR-010 Layered Architecture Accepted Rapid development
ADR-011 3 Bounded Contexts Superseded Original 3-context proposal; replaced by the 4-context model
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: The individual ADR files are stored in the decisions/ folder alongside this document and are linked from the table above.

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
Microservices Deployment complexity Monolith (bounded contexts in one process)
Database Installation complexity File-based (JSON/CSV)

Note: Some originally rejected options were later adopted as the tool matured beyond the initial 5-week MVP: the code now uses hexagonal ports/adapters within layered bounded contexts, an event bus for cross-context integration, and a Streamlit web dashboard for visualization (instead of the originally planned Matplotlib PNG output).

Rejected Technology Options

Technology Reason for Rejection MVP Alternative
FastAPI Web API not required Typer CLI (run / optimize)
PostgreSQL Database setup too complex CSV/JSON files
Docker Container overhead Native Python
Vue.js Dedicated frontend not required Streamlit + Plotly dashboard
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 + hexagonal ports/adapters within contexts Interface preparation Full hexagonal architecture
Integration Direct method calls + Event bus Repository pattern Fully event-driven
Storage File-based (JSON/CSV) Repository abstraction Database + Event Store
Visualization Streamlit + Plotly dashboard (reads CSV/JSON) Shared data export Hosted web frontend
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