7. Deployment View (MVP)¶

7.1 Deployment Overview¶

Desktop Application Architecture¶

graph TB
    subgraph "Developer Machine"
        subgraph "PopUpSim MVP"
            Python[Python 3.13+<br/>Runtime Environment]
            App[PopUpSim Application<br/>main.py + src/]
            Config[Configuration Files<br/>config/]
            Output[Output Directory<br/>output/]
        end

        subgraph "Dependencies"
            SimPy[SimPy Framework]
            Typer[Typer CLI]
            Pandas[Pandas]
            Pydantic[Pydantic]
            Streamlit[Streamlit + Plotly<br/>Dashboard]
        end
    end

    App --> Python
    App --> Config
    App --> Output
    Python --> SimPy
    Python --> Typer
    Python --> Pandas
    Python --> Pydantic
    Python --> Streamlit
    Streamlit --> Output

    classDef app fill:#4caf50,stroke:#2e7d32,stroke-width:2px,color:#fff
    classDef deps fill:#ff9800,stroke:#e65100,stroke-width:2px,color:#fff
    classDef files fill:#9e9e9e,stroke:#616161,stroke-width:2px,color:#fff

    class Python,App app
    class SimPy,Typer,Pandas,Pydantic,Streamlit deps
    class Config,Output files

7.2 Installation¶

Setup Process¶

Dependencies¶

Core dependencies are managed in pyproject.toml. Key requirements:

• Python 3.13+ - Latest stable Python version, provides improved type system and performance
• SimPy - Discrete event simulation (ADR-006)
• Pydantic 2.x - Data validation (ADR-008)
• Typer - CLI framework (run / optimize commands)
• Streamlit + Plotly - Interactive dashboard and charts (replaces the originally planned Matplotlib approach; see superseded ADR-009)
• Pandas - CSV/data processing

See pyproject.toml for exact pinned versions.

Development tools: - Ruff (formatting & linting) - MyPy (type checking with disallow_untyped_defs = true) - Pytest (unit testing)

Optional dependencies: - MkDocs toolchain (documentation generation)

See pyproject.toml and Section 7.10 for complete dependency list.

7.3 Directory Structure¶

Current Project Structure¶

dac-migration-dss-popupsim/
├── popupsim/                   # Main Package
│   ├── backend/               # Backend Application
│   │   ├── src/               # Source Code
│   │   │   ├── main.py                     # CLI entry point (Typer: run / optimize)
│   │   │   ├── application/                # Cross-context orchestration
│   │   │   │   ├── simulation_service.py   # SimulationApplicationService (drives SimPy)
│   │   │   │   ├── context_registry.py     # Registers & drives context lifecycles
│   │   │   │   └── workflow_strategy.py
│   │   │   ├── contexts/                   # Bounded contexts (DDD)
│   │   │   │   ├── configuration/          # Configuration Context (domain/application/infrastructure)
│   │   │   │   ├── external_trains/        # External Trains Context
│   │   │   │   ├── railway_infrastructure/ # Railway Infrastructure Context
│   │   │   │   └── retrofit_workflow/      # Retrofit Workflow Context (simulation + reporting)
│   │   │   ├── optimizer/                  # Two-phase scenario optimization (search/harness)
│   │   │   ├── infrastructure/             # Technical infrastructure (event_bus, logging, tracking)
│   │   │   ├── shared/                     # Shared kernel (domain, i18n, validation, value_objects)
│   │   │   └── __init__.py
│   │   ├── tests/             # Unit, validation, and integration tests
│   │   │   ├── unit/          # Unit tests mirroring the contexts/ layout
│   │   │   ├── validation/    # Scenario/timeline validation tests
│   │   │   ├── fixtures/      # Test fixtures (JSON/CSV)
│   │   │   └── conftest.py    # Pytest configuration
│   │   └── README.md          # Backend documentation
│   ├── frontend/              # Streamlit dashboard (dashboard.py + dashboard_components/)
│   └── __init__.py
├── Data/                       # Example Data
│   ├── examples/              # Example scenarios
│   │   ├── small_scenario/
│   │   ├── medium_scenario/
│   │   └── large_scenario/
│   └── README.md
├── docs/                       # Documentation
│   ├── architecture/          # Full architecture docs
│   ├── mvp/                   # MVP architecture docs
│   │   ├── architecture/
│   │   └── development/
│   ├── requirements/          # Requirements & use cases
│   └── README.md
├── .github/                    # GitHub Configuration
│   ├── workflows/             # CI/CD workflows
│   │   ├── python-backend.yaml    # Backend CI
│   │   └── docs.yml               # Docs deployment
│   └── actions/               # Custom actions
├── setup/                      # Setup Scripts
│   └── dev/
│       └── set_commit_msg_hooks.py
├── pyproject.toml              # Project configuration
├── uv.lock                     # Dependency lock file
├── mkdocs.yml                  # Documentation config
├── README.md                   # Project README
├── LICENSE                     # Apache 2.0 License
└── CONTRIBUTING.md             # Contribution guidelines

Building Block to Deployment Mapping¶

This table maps the bounded contexts from Section 5 to their deployment locations:

Key Observations: - All bounded contexts run in single Python process (desktop application) - All components reside in process memory (no distributed deployment) - Only data artifacts (config files, results) use file system storage - No database - all state is transient or file-based - No network - all communication is in-process method calls or event bus

Current Implementation Status¶

Implemented:

7.4 Execution Environment¶

Runtime Requirements¶

Note: Resource requirements will be measured during MVP implementation with realistic scenarios. The following are known requirements:

Command Line Interface¶

The CLI is built with Typer and exposes two subcommands: run and optimize.

# Run a simulation for a scenario directory
uv run python popupsim/backend/src/main.py run \
  --scenario Data/examples/ten_trains_two_days_baseline/ \
  --output output/

# Verbose output
uv run python popupsim/backend/src/main.py run \
  --scenario Data/examples/ten_trains_two_days_baseline/ --verbose

# Optimize task priorities via two-phase adaptive coordinate search
uv run python popupsim/backend/src/main.py optimize \
  --scenario Data/examples/ten_trains_two_days_baseline/ \
  --n-random 500 --n-workers 10 --k-starts 5 --max-rounds 5 \
  --results-json optimization_results.json

# Help
uv run python popupsim/backend/src/main.py --help
uv run python popupsim/backend/src/main.py run --help
uv run python popupsim/backend/src/main.py optimize --help

7.5 Configuration Management¶

Configuration File Locations¶

graph TB
    subgraph "Configuration Sources"
        Default[Default Config<br/>Built-in Values]
        Files[Config Files<br/>config/ directory]
        CLI[Command Line<br/>Arguments]
    end

    subgraph "Configuration Merge"
        Merger[Config Merger<br/>Priority Order]
    end

    subgraph "Final Config"
        Runtime[Runtime Configuration<br/>Used by Simulation]
    end

    Default --> Merger
    Files --> Merger
    CLI --> Merger
    Merger --> Runtime

    classDef source fill:#e3f2fd
    classDef process fill:#e8f5e8
    classDef result fill:#fff3e0

    class Default,Files,CLI source
    class Merger process
    class Runtime result

Configuration Priority¶

1. Command Line Arguments (Highest Priority)
2. Config Files (config/ directory)
3. Default Values (Built-in)

7.6 Output Management¶

Result Files¶

graph TB
    subgraph "MVP Output Generation"
        Simulation[Simulation Results]

        subgraph "Output Formats"
            CSV[CSV Files<br/>wagon_journey, locomotive_movements,<br/>rejected_wagons, resource_* streams]
            JSON[JSON Metrics<br/>summary_metrics.json]
            LOG[Event Log<br/>events.log]
        end

        subgraph "Output Locations"
            OutputDir[output/<br/>Default Directory]
            CustomDir[Custom Directory<br/>--output parameter]
        end

        Dashboard[Streamlit + Plotly<br/>Dashboard]
    end

    Simulation --> CSV
    Simulation --> JSON
    Simulation --> LOG

    CSV --> OutputDir
    JSON --> OutputDir
    LOG --> OutputDir

    CSV -.-> CustomDir
    JSON -.-> CustomDir
    LOG -.-> CustomDir

    OutputDir --> Dashboard

    classDef simulation fill:#4caf50,stroke:#2e7d32
    classDef format fill:#ff9800,stroke:#e65100
    classDef location fill:#9e9e9e,stroke:#616161

    class Simulation simulation
    class CSV,JSON,LOG format
    class OutputDir,CustomDir,Dashboard location

7.7 Error Handling & Logging¶

Logging Configuration¶

# Logging Setup
import logging
from typing import NoReturn

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('output/simulation.log'),
        logging.StreamHandler(),  # Console output
    ],
)

Error Recovery Strategy¶

7.8 Performance Monitoring¶

Resource Usage¶

Note: Actual resource usage will be measured during MVP implementation. The following aspects will be monitored:

graph TB
    subgraph "MVP Performance Metrics"
        subgraph "Memory Usage"
            ConfigMem[Config Loading<br/>To be measured]
            SimMem[Simulation Runtime<br/>To be measured]
            OutputMem[Output Generation<br/>To be measured]
        end

        subgraph "CPU Usage"
            SetupCPU[Setup Phase<br/>Low CPU]
            SimCPU[Simulation Phase<br/>High CPU]
            OutputCPU[Output Phase<br/>Medium CPU]
        end

        subgraph "Disk I/O"
            ReadIO[Config Reading<br/>Sequential]
            WriteIO[Result Writing<br/>Sequential]
        end
    end

    classDef memory fill:#e3f2fd
    classDef cpu fill:#e8f5e8
    classDef disk fill:#fff3e0

    class ConfigMem,SimMem,OutputMem memory
    class SetupCPU,SimCPU,OutputCPU cpu
    class ReadIO,WriteIO disk

7.9 Distribution Strategy¶

Packaging Options¶

Distribution Flow¶

graph LR
    A[Source Code<br/>Git Repository] --> B[Zip Archive<br/>Release Package]
    B --> C[PyInstaller<br/>Executable]
    C --> D[Docker Image<br/>Container]

    A -.->|MVP Current| B
    B -.->|Future| C
    C -.->|Future| D

    classDef current fill:#4caf50,stroke:#2e7d32
    classDef future fill:#ff9800,stroke:#e65100

    class A,B current
    class C,D future

7.10 Technology Stack Summary¶

Core Technologies¶

Development Tools¶

Deployment Model¶

Current: Desktop application (local execution) - File-based configuration (JSON/CSV) - File-based output (CSV/JSON/log) - Local Streamlit dashboard for visualization (runs as a separate process) - Single-user

Future: Web application (cloud-ready) - Hosted web interface - Database storage - Multi-user support - Distributed execution

7.11 Quality Goals and Deployment¶

The MVP deployment model directly supports the quality goals defined in Section 1.2:

Deployment Rationale¶

The desktop deployment model was chosen to maximize rapid development (Priority 1) and simple installation (Priority 4) for the MVP phase:

• No infrastructure complexity - Eliminates server setup, database configuration, and network dependencies
• Fast feedback loops - Developers can test changes immediately without deployment
• Minimal barriers - Strategic planners can run simulations with basic Python knowledge
• Version control friendly - All configuration is text-based and can be tracked in Git

Future evolution: The full version will add web interface and database storage while maintaining the core simulation engine developed in the MVP.

7.12 Deployment Scenarios¶

Scenario 1: Developer Deployment¶

User: Software developer working on PopUpSim MVP

Goal: Set up development environment for implementing new features

Prerequisites: - Git installed - Python 3.13+ installed - Text editor or IDE

Deployment Steps:

# 1. Clone repository
git clone https://github.com/open-rail-association/dac-migration-dss-popupsim.git
cd dac-migration-dss-popupsim

# 2. Install uv package manager
pip install uv

# 3. Install dependencies
uv sync

# 4. Run tests to verify setup
uv run pytest

# 5. Run simulation with example data
uv run python popupsim/backend/src/main.py run --scenario Data/examples/ten_trains_two_days_baseline/ --output output/

# 6. Set up pre-commit hooks (optional)
uv run python setup/dev/set_commit_msg_hooks.py

Environment: - Full source code access - Read/write permissions - Can modify code and run tests - CI/CD runs on push to GitHub

Typical Workflow: 1. Create feature branch 2. Implement changes with type hints 3. Run uv run ruff format . and uv run mypy backend/src/ 4. Run uv run pytest to verify tests pass 5. Commit and push for CI/CD validation

Scenario 2: Strategic Planner Deployment¶

User: Strategic Migration Planner testing standardized workshop designs (US-001, US-002)

Goal: Run simulations to compare different workshop configurations

Prerequisites: - Python 3.13+ installed - Basic command-line knowledge - Received PopUpSim release package (zip archive)

Deployment Steps:

# 1. Extract release package
unzip popupsim-mvp-v0.1.0.zip
cd popupsim-mvp-v0.1.0

# 2. Install uv package manager
pip install uv

# 3. Install dependencies
uv sync

# 4. Verify installation
uv run python popupsim/backend/src/main.py --help

# 5. Run simulation with example scenario
uv run python popupsim/backend/src/main.py run --scenario Data/examples/ten_trains_two_days_baseline/ --output output/

# 6. Review results
ls output/
# wagon_journey.csv, locomotive_movements.csv, rejected_wagons.csv,
# summary_metrics.json, resource_states.csv, events.log, scenario/

# 7. (Optional) Launch the dashboard to visualize results
uv run streamlit run popupsim/frontend/dashboard.py

Environment: - Read-only source code - Can create custom configuration files - Can run simulations with different parameters - Results saved to output/ directory

Typical Workflow (US-001): 1. Copy example scenario: cp -r Data/examples/medium_scenario/ my_workshop_4stations/ 2. Edit my_workshop_4stations/scenario.json (change station count to 4) 3. Run simulation: uv run python popupsim/backend/src/main.py run --scenario my_workshop_4stations/ --output output/4stations/ 4. Repeat for 2 stations and 6 stations 5. Compare results in output/ directory 6. Select optimal configuration

Scenario 3: Company Planner Deployment¶

User: Company Planner assessing capacity for planned workshop (US-003, US-004)

Goal: Import company infrastructure data and assess if workshop meets capacity targets

Prerequisites: - Python 3.13+ installed - Company infrastructure data (CSV files) - Received PopUpSim release package

Deployment Steps:

# 1-3. Same as Strategic Planner (extract, install uv, uv sync)

# 4. Prepare a scenario directory from company data
#    Assemble the scenario files (scenario.json + referenced topology,
#    tracks, workshops, locomotives, routes, and train schedule) following
#    the format of the bundled examples under Data/examples/.
mkdir my_company_scenario
# ... populate my_company_scenario/ with the company's configuration files ...

# 5. Run capacity assessment (US-004)
uv run python popupsim/backend/src/main.py run \
  --scenario my_company_scenario/ \
  --output output/company_assessment/

# 7. Review capacity assessment
cat output/capacity_assessment.csv
# Check if actual throughput >= target throughput

Environment: - Read-only source code - Company-specific data files - Can import and validate infrastructure - Results show pass/fail for capacity targets

Typical Workflow (US-004): 1. Import company infrastructure (US-003) 2. Set capacity target in scenario (e.g., 500 wagons/week) 3. Run week-long simulation (168 hours) 4. Review capacity assessment results 5. If target not met, analyze bottlenecks 6. Adjust workshop layout and re-run

Deployment Comparison¶