SW Modeling

In the context of modern software engineering, modeling is a disciplined engineering practice used to manage complexity, ensure architectural consistency, and bridge the gap between requirements and implementation.

System to Software Interaction: In the Organization engineering lifecycle, Software Modeling acts as the downstream continuation of System Engineering.

While system tools (like Capella / Melody Advance) define the high-level Physical Architecture (identifying which components are software), the practices and tools listed on this page take those physical components to design the internal software logic, classes, data models, and interfaces.

Modeling Practices

Our engineering landscape distinguishes between two primary practices, supplemented by strict interface management:

Formal Software Modeling

For complex systems, particularly in Large Software/System Applications, we adopt approaches like Model-Driven Development (MDD) and Component-Based Software Engineering (CBSE):

• The Practice: Architects create normative models that serve as a Single Source of Truth. This phase often ingests the system-level architectures and constraints to begin detailed software design.
• The Value: This practice allows for automated Code Generation, rigorous interface definition, and early validation of software constraints (SW/HW dependencies).
• Recommended Tools: MelodyCCM , Enterprise Architect .

Top-Down Interface Management

Process:
Interfaces are defined first in the System architecture. The software team models these boundaries using formal ports and connectors in tools like MelodyCCM or Enterprise Architect.

Deliverable:
This process supports the generation of and rigorously structures Interface Control Documents (ICDs), ensuring that independent teams (e.g., Team A building Software 1, Team B building Hardware 2) integrate successfully.

Agile Modeling

In fast-paced delivery environments or for MVP (Minimum Viable Product) development, the focus shifts toward agility and Just-Enough documentation (a principle formalized by Scott Ambler in Agile Modeling ).

Practice:
Architects and developers use lightweight modeling techniques to produce just enough design artefacts to support communication and decision-making. This encompasses:

• Diagram-as-Code: Architecture expressed as text (PlantUML , Mermaid , Structurizr/C4 , …). Diagrams live alongside source code in Git repositories, enabling version control and CI/CD integration.

  Teams should be aware that there is no semantic validation.

  A diagram can be syntactically correct and render successfully while still depicting architecturally incorrect relationships. Governance and peer review via Merge Requests remain essential.

• Visual/Sketching tools: GUI-based tools for collaborative design sessions (draw.io , Excalidraw , …).

Value:
Drastically reduces documentation overhead, integrates naturally into CI/CD pipelines, and keeps architecture visible and reviewable by the whole team.

Recommended Tools: PlantUML , Draw.io .

Bottom-Up Interface Management

Process

For software-to-software communication (e.g., web services), interfaces are managed using a “Contract First” approach. The API specification is written and agreed upon before any implementation begins, allowing both producer and consumer teams to develop independently against the same contract. The actual interface contract could be expressed in OpenAPI/Swagger (for REST APIs) for instance. PlantUML or Mermaid sequence diagrams serve as communication and documentation aids around that contract, illustrating interaction flows and expected behavior but do not replace the spec itself.

Deliverable

Both the API spec and the supporting diagrams live in Git alongside the code, updated via Merge Requests and CI/CD pipelines.

Methodology & Evaluation Approach

A study was conducted to ensure that software architects have the right tools across the full spectrum of physical components from deeply embedded, hardware-dependent systems to compute-intensive platforms.

The evaluation was based on three main axes:

1. Capabilities Coverage: Functional fit for daily architectural activities.
2. Code Generation: Ability to transform models into production-ready or skeleton code.
3. Tooling Ecosystem (Extra-Technical): Evaluation of licensing costs, support, SaaS readiness (multi-tenancy), and user management.

Project Scopes considered:

• Scale: From small agile teams to large-scale cross-country delivery.
• Context: From rapid MVP development to long-term product maintenance.
• Constraints: High Software Performance and Hardware dependencies.

After a comprehensive evaluation, the decision-making process prioritized technical excellence alongside cost-efficiency.

Application of Modeling & Targeted Use Cases

The appropriate modeling approach depends on several factors:

• The goal pursued (System-to-Software Transition, Legacy System Modernization),
• The criticality level of the project (e.g., Safety-Critical & Certified Software),
• The target architectural style (e.g., API & Microservices).

The following use cases illustrate how these factors drive different modeling practices in our environment:

System-to-Software Transition

• Application: Translating system-level operational workflows into concrete software architectures.
• Use Case: Taking a functional chain from a System model and designing the internal software components, state machines, and class structures required to implement it.

Legacy System Modernization

• Application: Understanding undocumented code.
• Use Case: Generating class or sequence diagrams directly from an existing codebase to identify refactoring opportunities or document technical debt.

Safety-Critical & Certified Software

• Application: Ensuring complete traceability from requirements down to generated code.
• Use Case: Avionics (DO-178C / DO-331), railway, or defense systems where formal models act as the definitive specification for certification authorities.

API & Microservices Design

• Application: Visualizing network communications and data contracts.
• Use Case: Drawing sequence diagrams and component diagrams to define how distributed microservices interact before writing the actual APIs.

Software Recommended Tools

Final Decision Matrix

Selected Tools Profiles

MelodyCCM

• Position: Best-in-class Technical Tool for specialized software design within Organization.
• Strengths: Ranked 1st in Capability Coverage, Code Generation, and Tooling Capabilities. Developed in a “Make” approach, it evolves to address Organization needs and engineering processes. It provides an excellent bridge for taking System models and converting them into Component-Based Software logic.
• Limitations: No internal user management; requires external management or dedicated focus on the design layer.

Enterprise Architect

• Position: Comprehensive, general-purpose modeling tool for large-scale, multi-team environments.
• Strengths: Extremely high coverage of modeling needs (UML/SysML). It provides a robust, shared repository that supports multi-team collaboration and acts as a bridge between System engineers and Software engineers working within the same project ecosystem.
• Limitations: Can be “oversized” and cumbersome for small projects. The tool’s flexibility comes with significant complexity: teams typically require dedicated training, particularly around repository management, baseline configuration, and cross-team collaboration features, basic diagramming has a gentler learning curve, but unlocking the full value of EA goes well beyond that.

PlantUML

• Position: Standard for text-to-diagram workflows in Agile environments.
• Strengths: Best for small to medium projects. Allows architects to version-control their diagrams (Git) and integrate into CI/CD pipelines. In this environment, PlantUML diagrams are rendered via the centralized Kroki service — no local installation required.
• Limitations: Limited layout control as the engine auto-positions elements; large diagrams can become difficult to read. Additionally, because PlantUML is a purely textual notation with no semantic meta-model, it is possible to produce diagrams that render correctly but are architecturally inconsistent — making peer review through Merge Requests an important safeguard.

Draw.io

• Position: Intuitive visual sketching tool, also available as diagrams.net.
• Strengths: Highly intuitive drag-and-drop interface. Excellent for simple projects where formal modeling rigor is not required.
• Limitations: Lacks an underlying semantic meta-model (it is purely visual). It does not support automated code generation or formal traceability to system requirements.

Software Factory with Kroki

To support the Diagram-as-Code practice, the Software Factory provides Kroki as a centralized service integrated directly into GitLab .

Kroki provides a unified API for a massive range of modeling tools. Instead of installing multiple local binaries, you can render diagrams directly from your Markdown files in GitLab or via simple HTTP calls.

By using Kroki, you can render PlantUML diagrams and many others types ):

Why use Kroki in the Software Factory?

1. Zero Install: No need for local Java or Graphviz installations; everything is rendered by the centralized service.
2. Native GitLab integration: Diagrams can be rendered directly within README.md, documentation, and Wiki pages in GitLab.
3. Consistency and version-controlled output: All team members see the same diagram, rendered from Git reinforcing the Diagram-as-Code practice.