Practice Guide: Modeling ML-Enabled System Architectures¶

This guide shows how to use the Linked.Archi ML-Enabled Systems extension to create architecture descriptions for systems that contain machine learning components. It addresses the gap identified by Moin et al. (2023) — that existing architecture frameworks lack stakeholders, viewpoints, and model kinds for data scientists, data engineers, and ML engineers.

Source: Enhancing Architecture Frameworks by Including Modern Stakeholders and their Views/Viewpoints (Moin, Badii, Günnemann, Challenger)

Extension artifacts: - extensions/ml-systems/ml-systems-onto.ttl — Elements, relationships, stakeholders, concerns, viewpoints - extensions/ml-systems/ml-systems-tax.ttl — SKOS taxonomy (by lifecycle phase, component role, stakeholder domain) - extensions/ml-systems/ml-systems-shapes.ttl — SHACL governance rules - extensions/ml-systems/ml-systems-metamodel.ttl — Metamodel manifest (entry point) - extensions/ml-systems/ml-quality-attributes.ttl — ML-specific quality attributes - examples/ml-fraud-detection/ml-fraud-detection-model.ttl — Complete worked example

The Problem¶

Moin et al. surveyed 61 subject matter experts and found that:

Missing stakeholders — Data scientists, data engineers, ML engineers, and ethics officers are not recognized in TOGAF, DoDAF, Zachman, or the 4+1 model
Missing viewpoints — No architecture viewpoint frames the concerns of ML practitioners (model performance, data quality, drift, explainability, fairness)
Missing model kinds — ML practitioners use different notations (computational graphs, mathematical formalisms, pipeline DAGs) that existing frameworks don't accommodate
The ML Mismatch problem — Data scientists and software engineers use different vocabularies, tools, and quality metrics, leading to incorrect assumptions at integration boundaries (Lewis et al. 2021)

The Linked.Archi approach addresses all four gaps through its knowledge graph foundation: stakeholders, concerns, and viewpoints are first-class ontology resources; the unified graph enables cross-domain queries; and presentation contexts allow the same data to be rendered in different notations for different audiences.

Quick Start¶

Step 1: Import the Extension¶

Your ontology imports the ML extension alongside any other modeling language you use:

@prefix mlsys: <https://meta.linked.archi/ml-systems/onto#> .
@prefix am:    <https://meta.linked.archi/archimate3/onto#> .
@prefix arch:  <https://meta.linked.archi/core#> .

<https://model.example.com/my-system#>
    a           owl:Ontology ;
    owl:imports <https://meta.linked.archi/ml-systems/onto#> ;
    owl:imports <https://meta.linked.archi/archimate3/onto#> ;  ## optional — if you also use ArchiMate
.

Step 2: Model Your ML Components¶

Use the ML element types to describe your system's ML landscape:

@prefix mlsys: <https://meta.linked.archi/ml-systems/onto#> .
@prefix :      <https://model.example.com/my-system#> .

:RecommendationModel
    a                          mlsys:MLModel ;
    skos:prefLabel             "Product Recommendation Model v2.1"@en ;
    mlsys:hasModelVersion      "2.1.0" ;
    mlsys:hasModelArchitecture "Two-tower neural network (user tower + item tower)" ;
    mlsys:hasFramework         "TensorFlow 2.15" ;
    mlsys:hasPerformanceMetric "NDCG@10=0.42, recall@50=0.31" ;
    mlsys:trainedOn            :UserInteractionDataset ;
    mlsys:registeredIn         :MLRegistry ;
    mlsys:hasMonitoringPlan    :RecoMonitor ;
.

:UserInteractionDataset
    a                    mlsys:Dataset ;
    skos:prefLabel       "User Interaction Dataset v4"@en ;
    mlsys:hasDataLineage :ClickstreamDB, :PurchaseDB ;
.

:RecoTrainingPipeline
    a               mlsys:TrainingPipeline ;
    skos:prefLabel  "Recommendation Training Pipeline"@en ;
    mlsys:producesModel :RecommendationModel ;
.

:RecoServingService
    a                          mlsys:ServingInfrastructure ;
    skos:prefLabel             "Recommendation Serving Service"@en ;
    mlsys:serves               :RecommendationModel ;
    mlsys:hasServingLatencySLA "p99 < 200ms" ;
.

Step 3: Model the ML/SE Integration Boundary¶

This is the critical step — documenting the interface between ML and non-ML components:

## Direct triple for graph traversal
:RecoServingService mlsys:integratesWith :ProductCatalogService .

## Qualified integration with contract metadata
:RecoServingService mlsys:qualifiedIntegratesWith :integration-reco-catalog .
:integration-reco-catalog
    a                    mlsys:IntegratesWith ;
    arch:source          :RecoServingService ;
    arch:target          :ProductCatalogService ;
    skos:prefLabel       "Recommendation → Catalog Integration"@en ;
    skos:definition      '''Recommendation service calls catalog service to enrich
scored item IDs with product metadata. Contract: send list of item IDs,
receive product details. Fallback: return popular items if catalog
service is unavailable.'''@en ;
    ## When RDF 1.2 tooling is available, add:
    ## rdf:reifies <<( :RecoServingService mlsys:integratesWith :ProductCatalogService )>> ;
.

Step 4: Validate with SHACL¶

Run the SHACL shapes to check governance compliance:

.scripts/validate.sh --shacl ml-systems

The shapes enforce rules like: - Every mlsys:MLModel must have a version, training dataset, and monitoring plan - Every mlsys:ServingInfrastructure must declare which model it serves - Every mlsys:IntegratesWith must have source, target, and documentation

The Extension in Detail¶

Element Types¶

The extension provides 10 element types organized by role in the ML lifecycle:

Element	Description	Lifecycle Phase
`mlsys:MLComponent`	Abstract base for all ML elements	—
`mlsys:MLModel`	A trained ML model	Development
`mlsys:Dataset`	A versioned data collection	Preparation
`mlsys:FeatureStore`	Centralized feature repository	Preparation
`mlsys:DataPipeline`	Data ingestion/transformation workflow	Preparation
`mlsys:TrainingPipeline`	End-to-end model training workflow	Development
`mlsys:ExperimentTracker`	Experiment logging and comparison	Development
`mlsys:ModelRegistry`	Versioned model catalog	Deployment
`mlsys:ServingInfrastructure`	Model serving runtime	Deployment
`mlsys:MonitoringComponent`	Production monitoring and alerting	Monitoring

All are subclasses of arch:Element, so they work with every Linked.Archi feature — viewpoints, qualified relationships, SHACL validation, SPARQL queries, and presentation contexts.

Stakeholders¶

The extension defines four stakeholder individuals (instances of arch:Stakeholder):

Stakeholder	Domain	Key Concerns
`mlsys:DataScientist`	Analytics Modeling	Model performance, feature quality, algorithm selection
`mlsys:DataEngineer`	Analytics Operations	Pipeline reliability, deployment, serving latency
`mlsys:MLEngineer`	Bridge (DS ↔ SE)	Productionization, integration, monitoring
`mlsys:EthicsOfficer`	ML Governance	Fairness, explainability, privacy, compliance

Concerns¶

10 ML-specific concerns, each an instance of arch:Concern:

Concern	Stakeholders Affected
`mlsys:ModelPerformanceConcern`	Data Scientist, ML Engineer
`mlsys:DataQualityConcern`	Data Scientist, Data Engineer
`mlsys:ModelDriftConcern`	Data Engineer, ML Engineer
`mlsys:ExplainabilityConcern`	Data Scientist, Ethics Officer
`mlsys:FairnessConcern`	Data Scientist, Ethics Officer
`mlsys:AdversarialRobustnessConcern`	Data Scientist, ML Engineer
`mlsys:MLArtifactVersioningConcern`	Data Engineer, ML Engineer
`mlsys:MLMonitorabilityConcern`	Data Engineer, ML Engineer
`mlsys:MLPrivacyConcern`	Ethics Officer
`mlsys:MLSECollaborationConcern`	All (the ML Mismatch problem)

Viewpoints¶

5 viewpoints that frame the concerns above:

Viewpoint	Targets	Concerns Framed	View Type
Analytics Modeling	Data Scientist, ML Engineer	Model performance, data quality, explainability, fairness	Diagram
Analytics Operations	Data Engineer, ML Engineer	Drift, monitorability, versioning	Diagram
ML System Integration	All ML stakeholders	ML–SE collaboration	Diagram, Matrix
ML Ethics & Compliance	Ethics Officer	Fairness, explainability, privacy, robustness	Matrix, Catalog
ML Model Catalog	All ML stakeholders	Versioning, model performance	Catalog

Quality Attributes¶

8 ML-specific quality attributes (instances of ad:QualityAttribute):

mlqa:Explainability — Can predictions be understood and communicated?
mlqa:Fairness — Does the model treat groups equitably?
mlqa:AdversarialRobustness — Is the model resilient to adversarial attacks?
mlqa:MLMonitorability — Can production behavior be observed and alerted on?
mlqa:Reproducibility — Can experiments be exactly reproduced?
mlqa:DataPrivacy — Is training data privacy protected?
mlqa:Trustworthiness — Composite: explainability + fairness + robustness + privacy
mlqa:ModelFreshness — Does the model reflect current conditions?

Worked Example: Fraud Detection System¶

The examples/ml-fraud-detection/ml-fraud-detection-model.ttl file contains a complete architecture model for a real-time fraud detection system. It demonstrates:

System Overview¶

┌─────────────────────────────────────────────────────────────────┐
│                    Non-ML Components                            │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │ Payment      │  │ Transaction  │  │ Notification          │  │
│  │ Service      │  │ Database     │  │ Service               │  │
│  └──────┬───────┘  └──────┬───────┘  └───────────────────────┘  │
│         │                 │                      ▲              │
│─────────┼─────────────────┼──────────────────────┼──────────────│
│         │    ML/SE        │    Integration        │              │
│         │    Boundary     │    Boundary           │              │
│─────────┼─────────────────┼──────────────────────┼──────────────│
│         ▼                 ▼                      │              │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │ Fraud Model  │  │ Transaction  │  │ Fraud Model           │  │
│  │ Server       │  │ ETL Pipeline │  │ Monitor               │  │
│  └──────┬───────┘  └──────┬───────┘  └───────────┬───────────┘  │
│         │                 │                      │              │
│         ▼                 ▼                      │              │
│  ┌──────────────┐  ┌──────────────┐              │              │
│  │ Fraud        │  │ Feature      │              │              │
│  │ Detection    │  │ Store        ├──────────────┘              │
│  │ Model v3.1   │  │ (Feast)      │                             │
│  └──────┬───────┘  └──────────────┘                             │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │ Model        │  │ Training     │  │ Experiment            │  │
│  │ Registry     │  │ Pipeline     │  │ Tracker (MLflow)      │  │
│  └──────────────┘  └──────────────┘  └───────────────────────┘  │
│                    ML Components                                │
└─────────────────────────────────────────────────────────────────┘

What the Example Covers¶

ML elements — MLModel, Dataset, FeatureStore, TrainingPipeline, ServingInfrastructure, MonitoringComponent, ExperimentTracker, ModelRegistry, DataPipeline
Non-ML elements — PaymentService, TransactionDB, NotificationService, CaseManagementUI
Integration boundary — Qualified IntegratesWith relationships with contract metadata (latency budget, fallback policy, data schema)
Architecture decisions — ADR for model algorithm choice (XGBoost vs LSTM vs RandomForest) with forces, options, and rationale
Quality attribute scenarios — Drift detection response time, fairness audit
Stakeholder instances — Fraud data scientists, platform data engineers, payments software engineers, compliance officer

SPARQL Queries Against the Example¶

Which ML models integrate with which non-ML components?

PREFIX mlsys: <https://meta.linked.archi/ml-systems/onto#>
PREFIX arch:  <https://meta.linked.archi/core#>

SELECT ?mlComponent ?mlLabel ?nonMLComponent ?nonMLLabel WHERE {
    ?mlComponent mlsys:integratesWith ?nonMLComponent ;
                 skos:prefLabel ?mlLabel .
    ?nonMLComponent skos:prefLabel ?nonMLLabel .
    ?mlComponent a/rdfs:subClassOf* mlsys:MLComponent .
    FILTER NOT EXISTS { ?nonMLComponent a/rdfs:subClassOf* mlsys:MLComponent }
}

What is the full data lineage for a model?

PREFIX mlsys: <https://meta.linked.archi/ml-systems/onto#>

SELECT ?model ?dataset ?source WHERE {
    ?model a mlsys:MLModel ;
           skos:prefLabel ?modelLabel ;
           mlsys:trainedOn ?dataset .
    ?dataset mlsys:hasDataLineage ?source .
}

Which models lack monitoring plans? (governance gap)

PREFIX mlsys: <https://meta.linked.archi/ml-systems/onto#>

SELECT ?model ?label WHERE {
    ?model a mlsys:MLModel ;
           skos:prefLabel ?label .
    FILTER NOT EXISTS { ?model mlsys:hasMonitoringPlan ?monitor }
}

What decisions were influenced by explainability requirements?

PREFIX ad:   <https://meta.linked.archi/arch-decision#>
PREFIX mlqa: <https://meta.linked.archi/ml-systems/quality-attributes#>

SELECT ?decision ?decisionLabel ?force ?forceLabel WHERE {
    ?decision a ad:Decision ;
              skos:prefLabel ?decisionLabel ;
              ad:influencedByForce ?force .
    ?force ad:onQualityAttribute mlqa:Explainability ;
           skos:prefLabel ?forceLabel .
}

Cross-domain: Which ArchiMate application components depend on ML models? (When composed with the ArchiMate ontology)

PREFIX mlsys: <https://meta.linked.archi/ml-systems/onto#>
PREFIX am:    <https://meta.linked.archi/archimate3/onto#>

SELECT ?appComponent ?appLabel ?mlModel ?mlLabel WHERE {
    ?mlServing a mlsys:ServingInfrastructure ;
               mlsys:integratesWith ?appComponent ;
               mlsys:serves ?mlModel .
    ?appComponent a/rdfs:subClassOf* am:ApplicationComponent ;
                  skos:prefLabel ?appLabel .
    ?mlModel skos:prefLabel ?mlLabel .
}

Addressing the Article's Specific Recommendations¶

Recommendation 1: Identify ML Stakeholders¶

Article says: Data scientists and data engineers must be recognized as stakeholders.

Linked.Archi response: The extension defines four stakeholder individuals (mlsys:DataScientist, mlsys:DataEngineer, mlsys:MLEngineer, mlsys:EthicsOfficer) as instances of arch:Stakeholder. Because arch:Stakeholder is a subclass of arch:Element, these stakeholders can appear in architecture models — linked to concerns via arch:viewpointFramesConcern, to decisions via ad:supportedByStakeholder, and to viewpoints via arch:targetsStakeholder.

Recommendation 2: Analytics Modeling Viewpoint¶

Article says: Data scientists need a viewpoint for model architecture, training, and evaluation using mathematical notations and computational graphs.

Linked.Archi response: The mlsys:AnalyticsModelingViewpoint frames model performance, data quality, explainability, and fairness concerns. It targets data scientists and ML engineers, and includes ML model, training pipeline, dataset, feature store, and experiment tracker concepts.

The notation gap is addressed through Linked.Archi's presentation context mechanism — the same underlying knowledge graph can be rendered as: - Computational graph notation for data scientists (model architecture diagrams) - Pipeline DAG notation for data engineers (Airflow/Kubeflow-style) - UML component diagrams for software engineers (ML components as black boxes) - Catalog tables for governance (model inventory with metrics)

Recommendation 3: Analytics Operations Viewpoint¶

Article says: Data engineers need a viewpoint for model deployment, serving, and monitoring.

Linked.Archi response: The mlsys:AnalyticsOperationsViewpoint frames drift, monitorability, and versioning concerns. It targets data engineers and ML engineers, and includes serving infrastructure, monitoring component, model registry, data pipeline, and training pipeline concepts.

Recommendation 4: ML/SE Collaboration¶

Article says: Existing viewpoints must be adapted to enable communication between data scientists and software engineers.

Linked.Archi response: The mlsys:MLSystemIntegrationViewpoint explicitly addresses the ML Mismatch problem. The qualified mlsys:IntegratesWith relationship carries contract metadata (API format, latency SLA, data schema, fallback policy) that both sides can validate. SHACL shapes enforce that every integration point is documented.

The knowledge graph approach inherently solves the vocabulary problem — data scientists and software engineers query the same graph but see different views. A data scientist asks "which models have drifted?" while a software engineer asks "which services depend on models that have drifted?" — both queries traverse the same graph.

Recommendation 5: ML-Specific Quality Attributes¶

Article says: New quality attribute concerns (monitorability, explainability, fairness, adversarial robustness) must be formalized.

Linked.Archi response: The ml-quality-attributes.ttl file defines 8 ML-specific quality attributes as instances of ad:QualityAttribute. These integrate with the existing architecture decision framework — quality attribute scenarios (QAS) can reference ML quality attributes, and decisions can be traced to the ML-specific forces they address.

Recommendation 6: Ethics and Compliance¶

Article says: Ethics committees need visibility into ML system behavior.

Linked.Archi response: The mlsys:MLEthicsViewpoint frames fairness, explainability, privacy, and adversarial robustness concerns. It targets the ethics officer stakeholder and uses matrix and catalog view types — suitable for compliance reporting. SHACL shapes can enforce that every model handling sensitive data has a fairness audit and explainability assessment.

Composing with Other Metamodels¶

The ML extension is designed to compose with any Linked.Archi metamodel. Common compositions:

ML + ArchiMate¶

Model ML components alongside ArchiMate elements. ML models become technology components that serve application services:

@prefix am:    <https://meta.linked.archi/archimate3/onto#> .
@prefix mlsys: <https://meta.linked.archi/ml-systems/onto#> .

:FraudScoringService a am:ApplicationService ;
    skos:prefLabel "Fraud Scoring Service"@en ;
    am:serves :PaymentAuthorizationProcess .

:FraudModelServer a mlsys:ServingInfrastructure ;
    mlsys:serves :FraudDetectionModel ;
    am:realizes :FraudScoringService .

ML + Architecture Decisions¶

Every ML design choice becomes a traceable decision:

@prefix ad:    <https://meta.linked.archi/arch-decision#> .
@prefix mlsys: <https://meta.linked.archi/ml-systems/onto#> .
@prefix mlqa:  <https://meta.linked.archi/ml-systems/quality-attributes#> .

:ADR-FeatureStoreChoice a ad:Decision ;
    skos:prefLabel "ADR-003: Adopt Feast as Feature Store"@en ;
    ad:influencedByForce :Force-FeatureConsistency, :Force-TrainServSkew ;
    ad:relatedConcept :FraudFeatureStore .

:Force-TrainServSkew a ad:QualityAttributeRequirement ;
    skos:prefLabel "Eliminate Train-Serve Skew"@en ;
    ad:onQualityAttribute mlqa:Reproducibility ;
    ad:qasResponseMeasure "Feature values at serving time match training time within 0.1% tolerance"@en .

ML + ADMIT Forces¶

Use ADMIT's 20 design forces as a checklist for ML system architecture:

@prefix admit: <https://meta.linked.archi/admit/onto#> .

:MLInfraForce a admit:PlatformForce ;
    skos:prefLabel "ML platform must support GPU and CPU model serving"@en ;
    ad:hasImportanceMeasure "high" .

:MLSecurityForce a admit:SecurityForce ;
    skos:prefLabel "Models must be protected against adversarial attacks and data poisoning"@en ;
    ad:hasImportanceMeasure "critical" .

ML + Backstage¶

Register ML components in the developer portal:

@prefix bs:    <https://meta.linked.archi/backstage/onto#> .
@prefix mlsys: <https://meta.linked.archi/ml-systems/onto#> .

:FraudScoringSystem a bs:System ;
    skos:prefLabel "Fraud Scoring System"@en ;
    bs:ownedBy :FraudAnalyticsTeam .

:FraudScoringAPI a bs:API ;
    skos:prefLabel "Fraud Scoring gRPC API"@en ;
    bs:providedBy :FraudScoringSystem .

:FraudModelServer a mlsys:ServingInfrastructure ;
    mlsys:integratesWith :FraudScoringSystem .

Validation¶

Syntax Validation¶

.scripts/validate.sh --syntax extensions/ml-systems/ml-systems-onto.ttl
.scripts/validate.sh --syntax extensions/ml-systems/ml-systems-tax.ttl
.scripts/validate.sh --syntax extensions/ml-systems/ml-systems-shapes.ttl
.scripts/validate.sh --syntax extensions/ml-systems/ml-systems-metamodel.ttl
.scripts/validate.sh --syntax extensions/ml-systems/ml-quality-attributes.ttl
.scripts/validate.sh --syntax examples/ml-fraud-detection/ml-fraud-detection-model.ttl

SHACL Validation¶

Once the SHACL profile is registered:

.scripts/validate.sh --shacl ml-systems

This validates that: - Every ML model has version, training dataset, and monitoring plan - Every serving infrastructure declares its model and latency SLA - Every integration point has source, target, and documentation - Every dataset has data lineage

References¶

Moin, A., Badii, A., Günnemann, S., & Challenger, M. (2023). Enhancing Architecture Frameworks by Including Modern Stakeholders and their Views/Viewpoints. arXiv:2308.05239
Lewis, G., Bellomo, S., & Ozkaya, I. (2021). Characterizing and Detecting Mismatch in Machine-Learning-Enabled Systems. ICSE-WAIN 2021.
Muccini, H. & Vaidhyanathan, K. (2021). Software Architecture for ML-Based Systems: What Exists and What Lies Ahead. WAIN 2021.
ISO/IEC/IEEE 42010:2022 — Architecture Description