# xmi-schema/xmi-schema-python architecture

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

- Interactive diagram: https://gitdiagram.com/xmi-schema/xmi-schema-python
- Repository: https://github.com/xmi-schema/xmi-schema-python

## Overview

##### Project type and purpose
- This is a Python library/package (full “src/xmi” package with versioned modules) whose purpose is to parse JSON representations of structural models (XMI) and expose them as Python objects.
- There is no frontend or service layer—this is a domain‐specific parser and model manager.

##### File structure
- Top level: configuration and CI (`.github/workflows`, `pyproject.toml`), install scripts, license, tests folder.
- `src/xmi/v1/`: core library code for version 1 of the XMI spec.
- `entities/`: Python classes for each domain object (curve member, material, cross‐section, node, etc.)
- `geometries/`: basic geometry primitives (points, lines, arcs)
- `relationships/`: mixins or helpers that link entities to geometry or to one another
- `xmi_manager.py`: the façade/orchestrator that reads JSON and builds the full model
- `xmi_model.py`: container for the assembled entity graph
- `constants.py`, `xmi_errors.py`, `xmi_utilities.py`: shared utilities and error definitions
- `tests/`: mirror of `src/` for test inputs and test scripts checking parsing correctness.
- `after_install_tests/`: sanity tests that run after the package is installed.

##### Key insights from README
- The library is under active development; most structural entities are done.
- XmiManager is the entry point and drives reading JSON → instantiating entity classes.

##### Components and interactions
a. Main components
- JSON Input (external files)
- XmiManager (parsing coordinator)
- XmiModel (holds all entity instances)
- Entities layer (each entity class grouped under `entities/`)
- Support layers:
- Enums (`enums/`)
- Geometries (`geometries/`)
- Relationships (`relationships/`)
- Utilities & Constants
b. Relationships & data flow
1. JSON Input → XmiManager.read( )
2. XmiManager uses utilities to validate JSON and dispatch to entity constructors
3. Each entity class may:
– Instantiate geometry primitives
– Mix in relationships to other entities/geometries
4. Entities are collected into XmiModel
5. XmiModel can be queried or exported by client code
c. Architectural patterns & design principles
- Layered modular design: separation between orchestration (manager), domain (entities), and support (enums, geometries, utilities)
- Single Responsibility: each entity class handles one concept
- Factory/Manager pattern: XmiManager is the factory that builds the object graph
- Versioning: code is namespaced under `v1`, making future versions easy to add
d. Key technologies/frameworks
- Python package structure (PEP 517/518 via `pyproject.toml`)
- pytest or unittest for tests
- JSON for data interchange

##### Elements
- Clear rectangular blocks for each module/package (e.g., “entities”, “geometries”, “relationships”).
- A distinct block for XmiManager and XmiModel.
- An “External JSON Input” block on the left.
- From JSON Input → XmiManager
- From XmiManager → Entities & Support modules
- From Entities → XmiModel
- Input data (e.g., gray)
- Processing components (XmiManager in blue)
- Domain model (entities in green)
- Utilities (enums/geometries in yellow)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Input
    JSONInput["External JSON Input"]:::input

    %% Manager and Model
    XmiManager["XmiManager"]:::manager
    XmiModel["XmiModel"]:::model

    %% Support Modules
    subgraph "Utilities & Support"
        Constants["constants.py"]:::utilities
        Utilities["xmi_utilities.py"]:::utilities
        Errors["xmi_errors.py"]:::error
        Base["xmi_base.py"]:::utilities
    end

    subgraph "Enums"
        Enum1["xmi_enums.py"]:::utilities
        Enum2["xmi_shape_enums.py"]:::utilities
        Enum3["xmi_structural_curve_member_enums.py"]:::utilities
        Enum4["xmi_structural_material_enums.py"]:::utilities
        Enum5["xmi_structural_surface_member_enums.py"]:::utilities
    end

    subgraph "Geometries"
        Geo1["xmi_arc_3d.py"]:::utilities
        Geo2["xmi_base_geometry.py"]:::utilities
        Geo3["xmi_line_3d.py"]:::utilities
        Geo4["xmi_point_3d.py"]:::utilities
    end

    subgraph "Relationships"
        Rel1["xmi_has_geometry.py"]:::utilities
        Rel2["xmi_has_line_3d.py"]:::utilities
        Rel3["xmi_has_point_3d.py"]:::utilities
        Rel4["xmi_has_segment.py"]:::utilities
        Rel5["xmi_has_structural_cross_section.py"]:::utilities
        Rel6["xmi_has_structural_material.py"]:::utilities
        Rel7["xmi_has_structural_node.py"]:::utilities
    end

    subgraph "Shapes"
        Shape["xmi_shape.py"]:::utilities
    end

    subgraph "Entities"
        Segment["xmi_segment.py"]:::domain
        CrossSection["xmi_structural_cross_section.py"]:::domain
        CurveMember["xmi_structural_curve_member.py"]:::domain
        Material["xmi_structural_material.py"]:::domain
        PointConnection["xmi_structural_point_connection.py"]:::domain
        Storey["xmi_structural_storey.py"]:::domain
        SurfaceMember["xmi_structural_surface_member.py"]:::domain
        Unit["xmi_structural_unit.py"]:::domain
    end

    %% Data Flow
    JSONInput -->|reads| XmiManager
    XmiManager -->|validates| Utilities
    XmiManager -->|loads constants| Constants
    XmiManager -->|on error| Errors
    XmiManager -->|dispatches enums| Enum1
    XmiManager --> Enum2
    XmiManager --> Enum3
    XmiManager --> Enum4
    XmiManager --> Enum5
    XmiManager -->|uses| Geo1
    XmiManager --> Geo2
    XmiManager --> Geo3
    XmiManager --> Geo4
    XmiManager --> Rel1
    XmiManager --> Rel2
    XmiManager --> Rel3
    XmiManager --> Rel4
    XmiManager --> Rel5
    XmiManager --> Rel6
    XmiManager --> Rel7
    XmiManager --> Shape
    XmiManager -->|constructs| Segment
    XmiManager --> CrossSection
    XmiManager --> CurveMember
    XmiManager --> Material
    XmiManager --> PointConnection
    XmiManager --> Storey
    XmiManager --> SurfaceMember
    XmiManager --> Unit
    Segment -->|collected in| XmiModel
    CrossSection --> XmiModel
    CurveMember --> XmiModel
    Material --> XmiModel
    PointConnection --> XmiModel
    Storey --> XmiModel
    SurfaceMember --> XmiModel
    Unit --> XmiModel
    XmiManager -->|builds| XmiModel

    %% Click Events
    click JSONInput "https://github.com/xmi-schema/xmi-schema-python/tree/main/after_install_tests/xmi/v1/test_inputs/"
    click XmiManager "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/xmi_manager.py"
    click XmiModel "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/xmi_model.py"
    click Segment "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/entities/xmi_segment.py"
    click CrossSection "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/entities/xmi_structural_cross_section.py"
    click CurveMember "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/entities/xmi_structural_curve_member.py"
    click Material "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/entities/xmi_structural_material.py"
    click PointConnection "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/entities/xmi_structural_point_connection.py"
    click Storey "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/entities/xmi_structural_storey.py"
    click SurfaceMember "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/entities/xmi_structural_surface_member.py"
    click Unit "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/entities/xmi_structural_unit.py"
    click Enum1 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/enums/xmi_enums.py"
    click Enum2 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/enums/xmi_shape_enums.py"
    click Enum3 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/enums/xmi_structural_curve_member_enums.py"
    click Enum4 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/enums/xmi_structural_material_enums.py"
    click Enum5 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/enums/xmi_structural_surface_member_enums.py"
    click Geo1 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/geometries/xmi_arc_3d.py"
    click Geo2 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/geometries/xmi_base_geometry.py"
    click Geo3 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/geometries/xmi_line_3d.py"
    click Geo4 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/geometries/xmi_point_3d.py"
    click Rel1 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/relationships/xmi_has_geometry.py"
    click Rel2 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/relationships/xmi_has_line_3d.py"
    click Rel3 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/relationships/xmi_has_point_3d.py"
    click Rel4 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/relationships/xmi_has_segment.py"
    click Rel5 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/relationships/xmi_has_structural_cross_section.py"
    click Rel6 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/relationships/xmi_has_structural_material.py"
    click Rel7 "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/relationships/xmi_has_structural_node.py"
    click Shape "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/shapes/xmi_shape.py"
    click Utilities "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/xmi_utilities.py"
    click Constants "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/constants.py"
    click Errors "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/xmi_errors.py"
    click Base "https://github.com/xmi-schema/xmi-schema-python/blob/main/src/xmi/v1/xmi_base.py"

    %% Styles
    classDef input fill:#dddddd,stroke:#999;
    classDef manager fill:#ADD8E6,stroke:#333;
    classDef model fill:#f0f0f0,stroke:#333;
    classDef utilities fill:#ffffcc,stroke:#333;
    classDef domain fill:#ccffcc,stroke:#333;
    classDef error fill:#ffcccc,stroke:#333;
```
