# uicrail/semanticrsm architecture

> Architecture diagram of the GitHub repository uicrail/semanticrsm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uicrail/semanticrsm
- Repository: https://github.com/uicrail/semanticrsm

## Overview

Based on our review of the file tree and the README, the project is SemanticRSM – a semantic re-casting of the Rail System Model (RSM) using direct RDF/OWL modelling. Its purpose is to translate and transform rail network data (from sources like OpenStreetMap, IFC files, and specific rail data such as SD1 or railML) into a semantically rich ontology that is backward compatible with earlier models, while introducing improvements in topology, navigability, and modularization of the domain concepts.

##### Main Components
- Data Sources and Input:
- Source_data (containing ISO, Scheibenberg, Baltic Network, IFC, and OSM examples)
- External models (e.g., DATEX II, SRTI Datex II, ERA, etc.)
- Import and Parsing Modules:
- Code/Import directory with submodules for OSM_import, SD1_import, drawIO_import, railML32_import (each handling a different input type)
- Utilities like helper_functions, ontology version comparisons and file converters
- Transformation Pipeline:
- Code/Graph_transformation modules that include a series of Python scripts (step01_split_linear_elements.py, step02_join_linear_elements.py, etc.) that handle geometric and topological transformations and integrate port properties.
- Ontology Modules:
- Ontologies folder with separate namespaces (CDM, CCS-TMS, DATEX2v3, ERA, etc.), each containing TTL and other RDF files to define the underlying vocabulary and relations.
- Export Functionality:
- Code/Export containing Python scripts to output transformed data into different formats (e.g., export_ifcAlignment_to_kml.py, export_ttl_to_kml.py)
- Web-based Demonstration/Interface:
- Flask folder with an __init__.py and page definitions that allow launching a local server for demonstration, providing a user interface and using sample data.
- Supporting Documents & Developer Tools:
- Prolog scripts for demo path finding (shortest path algorithms)
- Various build/configuration (git, Qodana, etc.) and developer tool directories (IDE caches, lsp, etc.)

##### Relationships and Interactions
- Data Flow: Data originates from diverse Source_data and External Models and flows into the Import modules via specialized converters.
- Transformation Pipeline: Once imported, the data is processed through a sequence of transformation scripts in the Graph_transformation directory. Each step (splitting, joining, port adding, slip functionality, meso ports) refines and evaluates the input data.
- Ontology Integration: The processed data is then mapped into RDF/OWL representations by utilizing the ontologies stored in the Ontologies directory (which are structured in a clear, modular way to maintain high cohesion and low coupling).

##### Architectural Patterns and Design Principles
- Modular design: Clear separation into import, transformation, and export modules.
- Pipeline/Sequential Processing: Data flows through distinct transformation stages.
- Layered system: Inputs, processing, ontology mapping, presentation (Flask demo), and support/documentation layers.
- Interoperability via standards: Use of RDF, OWL, SHACL, SPARQL; adherence to UIC standards.

##### Instructing the Principal Software Engineer
- Create distinct sections for:
– External Data Inputs (Source_data, External Models)
– Data Import and Preprocessing (all modules in Code/Import)
– Core Transformation Pipeline (present the sequential processing steps from Code/Graph_transformation)
– Semantic Mapping and Ontology Generation (including the modular ontologies)
– Export and Interface Presentation (Code/Export and Flask server)
- Architectural principle of modularity and backward compatibility through separate but inter-dependent modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Inputs
    SourceData["Source_data"]:::datasource
    ExternalModels["External Models"]:::datasource

    %% Data Import Layer
    subgraph "Data Import Layer"
        OSM_import["OSM_import"]:::importmod
        SD1_import["SD1_import"]:::importmod
        drawIO_import["drawIO_import"]:::importmod
        railML32_import["railML32_import"]:::importmod
    end

    %% Merge Imported Data
    ImportedData["Imported Data"]:::importmod

    %% Transformation Pipeline
    subgraph "Transformation Pipeline"
        Step1["step01_split_linear_elements"]:::transformation
        Step2["step02_join_linear_elements"]:::transformation
        Step3["step03_add_ports"]:::transformation
        Step4a["step04a_add_port_properties"]:::transformation
        Step4b["step04b_add_slip_functionality"]:::transformation
        Step5["step05_meso_ports"]:::transformation
    end

    %% Ontology Mapping
    OntologyNode["Ontologies"]:::ontology

    %% Export and Interface Presentation
    ExportNode["Export"]:::export
    FlaskDemo["Flask Demo"]:::web

    %% Support Tools Layer
    subgraph "Support Tools"
        Documentation["Documentation"]:::support
        Prolog["Prolog Scripts"]:::support
    end

    %% Data Flow Connections
    SourceData --> ImportedData
    ExternalModels --> ImportedData

    OSM_import --> ImportedData
    SD1_import --> ImportedData
    drawIO_import --> ImportedData
    railML32_import --> ImportedData

    ImportedData --> Step1
    Step1 --> Step2
    Step2 --> Step3
    Step3 --> Step4a
    Step4a --> Step4b
    Step4b --> Step5

    Step5 -->|"mapsRDFOWL"| OntologyNode
    OntologyNode -->|"exportsSemantic"| ExportNode
    OntologyNode -->|"providesUIDemo"| FlaskDemo

    %% Click Events
    click SourceData "https://github.com/uicrail/semanticrsm/tree/main/Source_data/OSM"
    click ExternalModels "https://github.com/uicrail/semanticrsm/tree/main/External Models/DATEX II v3"
    click OSM_import "https://github.com/uicrail/semanticrsm/tree/main/Code/Import/OSM_import"
    click SD1_import "https://github.com/uicrail/semanticrsm/tree/main/Code/Import/SD1_import"
    click drawIO_import "https://github.com/uicrail/semanticrsm/tree/main/Code/Import/drawIO_import"
    click railML32_import "https://github.com/uicrail/semanticrsm/tree/main/Code/Import/railML32_import"
    click Step1 "https://github.com/uicrail/semanticrsm/blob/main/Code/Graph_transformation/step01_split_linear_elements.py"
    click Step2 "https://github.com/uicrail/semanticrsm/blob/main/Code/Graph_transformation/step02_join_linear_elements.py"
    click Step3 "https://github.com/uicrail/semanticrsm/blob/main/Code/Graph_transformation/step03_add_ports.py"
    click Step4a "https://github.com/uicrail/semanticrsm/blob/main/Code/Graph_transformation/step04a_add_port_properties.py"
    click Step4b "https://github.com/uicrail/semanticrsm/blob/main/Code/Graph_transformation/step04b_add_slip_functionality.py"
    click Step5 "https://github.com/uicrail/semanticrsm/blob/main/Code/Graph_transformation/step05_meso_ports.py"
    click OntologyNode "https://github.com/uicrail/semanticrsm/tree/main/Ontologies/CDM"
    click ExportNode "https://github.com/uicrail/semanticrsm/tree/main/Code/Export"
    click FlaskDemo "https://github.com/uicrail/semanticrsm/blob/main/Flask/__init__.py"
    click Documentation "https://github.com/uicrail/semanticrsm/tree/main/Documentation"
    click Prolog "https://github.com/uicrail/semanticrsm/blob/main/Prolog/240606 Navigabilities.pl"

    %% Styles
    classDef datasource fill:#9fdf9f,stroke:#333,stroke-width:2px;
    classDef importmod fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef transformation fill:#ffd700,stroke:#333,stroke-width:2px;
    classDef ontology fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef export fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef web fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef support fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
