# twiniars/meros architecture

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

- Interactive diagram: https://gitdiagram.com/twiniars/meros
- Repository: https://github.com/twiniars/meros

## Overview

##### Project type and purpose
- Its purpose is to define a standardized metamodel (groups of ROS concepts) and to produce human-readable artifacts (documentation, tutorial, poster) that robotics engineers and students can use with SysML tools (e.g., Visual Paradigm).

##### File structure
- Top-level:
· doc/ – release procedures and thesis guidance (Markdown)
· src/ – all the source artifacts:
- img/ – graphical abstract, requirement packages, profiles, tutorial assets
- turtlesim-doc/ – concrete tutorial example in LaTeX
- meros-stereotypes.tex, meros.bib – core SysML profile definitions and bibliography
- Configuration & automation:
· GitHub Actions workflow (dependent-issues.yml)
· .gitignore, LICENSE, README.md, Tutorial.md

##### Key insights from README
- Core deliverable: a SysML‐based metamodel for ROS, with grouping concepts and multiple levels of detail.
- Outputs include a PDF documentation, a poster, and practical tutorials.
- Integrates with standard SysML tools for authoring and viewing.

##### Main components and their relationships
a. Source Artifact Layer
- LaTeX sources (.tex, .bib) for documentation & tutorials
- SysML project files (.vpp) and stereotype XML for the metamodel
b. Toolchain & Build Layer
- LaTeX compiler(s) to produce PDFs
- Visual Paradigm / SysML modeling tool that reads .vpp and XML stereotypes
- GitHub Actions for CI: auto‐build docs or validate dependencies
c. Publication & Distribution Layer
- GitHub Releases (artifact storage: documentation PDF, poster PDF)
- GitHub Pages or raw assets for image embedding
d. Consumer / Integration Layer
- Robotics engineers using ROS and SysML tools

##### Architectural patterns & design principles
- “Source→Build→Publish” pipeline pattern: clear separation of editable sources, automated build, and published artifacts.
- Modularity: documentation, metamodel, tutorial each in its own sub-folder.

##### Essential architectural elements
- The distinct separation between metamodel sources, documentation sources, toolchain, and output artifacts.
- The role of external SysML tooling (Visual Paradigm) as both a consumer and validator of the metamodel.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Development Layer
    subgraph "Development" 
        direction TB
        MMVPP["Metamodel Definition\n(vpp)"]:::source
        MXML["Metamodel Stereotypes\n(XML)"]:::source
        STEX["meros-stereotypes.tex"]:::source
        SBIB["meros.bib"]:::source
        MMDOC["Metamodel Documentation\n(LaTeX)"]:::source
        TUTDOC["Tutorial Documentation\n(LaTeX)"]:::source
        subgraph "Diagram Assets"
            direction TB
            GABS["meros-graphical-abstract.pptx"]:::source
            REQPKG["requirement_pkg"]:::source
            PROF["profile"]:::source
            MEROPKG["meros_pkg"]:::source
            RICOPKG["rico_pkg"]:::source
        end
        subgraph "Guides & Metadata"
            direction TB
            GUIDE1["HOW_TO_CREATE_RELEASE.md"]:::source
            GUIDE2["THESES_QUESTIONS_CHECK.md"]:::source
            README["README.md"]:::source
            TUTORIALMD["Tutorial.md"]:::source
            GITIGNORE[".gitignore"]:::source
            LICENSE["LICENSE"]:::source
        end
    end

    %% Build Pipeline Layer
    subgraph "Build Pipeline"
        direction TB
        GH["GitHub Actions"]:::external
        LATEX["LaTeX Compiler"]:::tool
        VP["Visual Paradigm"]:::external
    end

    %% Delivery Layer
    subgraph "Delivery"
        direction TB
        REL["GitHub Releases"]:::external
        DOCPDF["Documentation PDF"]:::output
        POSTPDF["Poster PDF"]:::output
    end

    %% Consumer Layer
    USERS["Robotics Engineers\n& Students"]:::consumer

    %% Connections
    %% Dev to Build
    MMVPP -->|"import"| VP
    MXML -->|"import stereotypes"| VP
    MMDOC -->|"compile"| LATEX
    TUTDOC -->|"compile"| LATEX
    STEX -->|"load macros"| LATEX
    SBIB -->|"load bibliography"| LATEX
    GH -->|"trigger build"| LATEX
    GH -->|"validate model"| VP

    %% Build to Delivery
    LATEX -->|"generate PDF"| DOCPDF
    VP -->|"export diagrams"| DOCPDF
    VP -->|"export diagrams"| POSTPDF
    GH -->|"publish artifacts"| REL
    DOCPDF -->|"release"| REL
    POSTPDF -->|"release"| REL

    %% Delivery to Consumer
    REL -->|"download"| USERS

    %% Click Events
    click MMVPP "https://github.com/twiniars/meros/blob/main/src/metamodel-doc/vp-project/meros_metamodel.vpp"
    click MXML "https://github.com/twiniars/meros/blob/main/src/metamodel-doc/vp-project/meros-vp-stereotypes.xml"
    click STEX "https://github.com/twiniars/meros/blob/main/src/meros-stereotypes.tex"
    click SBIB "https://github.com/twiniars/meros/blob/main/src/meros.bib"
    click MMDOC "https://github.com/twiniars/meros/blob/main/src/metamodel-doc/meros-metamodel-doc.tex"
    click TUTDOC "https://github.com/twiniars/meros/blob/main/src/turtlesim-doc/meros-turtlesim-doc.tex"
    click GABS "https://github.com/twiniars/meros/blob/main/src/img/meros-graphical-abstract.pptx"
    click REQPKG "https://github.com/twiniars/meros/tree/main/src/img/requirement_pkg"
    click PROF "https://github.com/twiniars/meros/tree/main/src/img/profile"
    click MEROPKG "https://github.com/twiniars/meros/tree/main/src/img/meros_pkg"
    click RICOPKG "https://github.com/twiniars/meros/tree/main/src/img/rico_pkg"
    click GUIDE1 "https://github.com/twiniars/meros/blob/main/doc/HOW_TO_CREATE_RELEASE.md"
    click GUIDE2 "https://github.com/twiniars/meros/blob/main/doc/THESES_QUESTIONS_CHECK.md"
    click README "https://github.com/twiniars/meros/blob/main/README.md"
    click TUTORIALMD "https://github.com/twiniars/meros/blob/main/Tutorial.md"
    click GITIGNORE "https://github.com/twiniars/meros/blob/main/.gitignore"
    click LICENSE "https://github.com/twiniars/meros/tree/main/LICENSE"
    click GH "https://github.com/twiniars/meros/blob/main/.github/workflows/dependent-issues.yml"
    click POSTPDF "https://github.com/twiniars/meros/tree/main/src/poster"

    %% Styles
    classDef source fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px
    classDef tool fill:#C8E6C9,stroke:#1B5E20,stroke-width:1px
    classDef output fill:#FFE0B2,stroke:#E65100,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#424242,stroke-width:1px
    classDef consumer fill:#F5F5F5,stroke:#9E9E9E,stroke-width:1px
```
