Architecture Practice from Scratch — Part 7: Tool Integration¶

Parts 5 and 6 produced the formal semantic assets — OWL ontology, SKOS taxonomy, viewpoints, SHACL shapes. These are the machine-readable source of truth. This final part connects them to tooling: the generation pipeline that produces browsable output, the build-or-buy decision for repository tools, and integration patterns for making the knowledge graph AI-accessible.

The series:

Stakeholder Discovery & Viewpoint Elicitation
Structuring Requirements into Viewpoints & Artifact Types
Metamodel Conceptualized
Governance & Lifecycle Management
Formal Metamodel Definition
Formal Governance & Validation
Tool Integration ← you are here

What We're Producing¶

Generation pipeline architecture — TTL → SPARQL → Markdown → multiple output formats
Build-or-buy decision framework — criteria for evaluating architecture repository tools
Integration patterns — how the metamodel connects to different tool architectures
AI accessibility — making the knowledge graph available to AI agents via MCP

The Generation Pipeline¶

The core insight: Markdown is the universal intermediate format. The same TTL source data produces all output formats through different rendering pipelines.

Architecture¶

┌──────────────┐     ┌───────────────┐     ┌──────────────┐     ┌──────────────────┐
│  TTL Files   │────▶│ SPARQL Queries │────▶│   Template   │────▶│  Output Format   │
│ (source of   │     │ (extract data) │     │  Engine      │     │                  │
│  truth)      │     │               │     │ (Handlebars/ │     │ • Markdown       │
│              │     │               │     │  Jinja)      │     │ • HTML (MkDocs)  │
│ • onto.ttl   │     │ • elements    │     │              │     │ • Confluence     │
│ • tax.ttl    │     │ • viewpoints  │     │ • catalog.md │     │ • PDF (Pandoc)   │
│ • model.ttl  │     │ • governance  │     │ • element.md │     │ • PPTX (Marp)    │
│ • shapes.ttl │     │ • compliance  │     │ • view.md    │     │                  │
└──────────────┘     └───────────────┘     └──────────────┘     └──────────────────┘

Step 1: SPARQL Extracts Data¶

The deliverable templates (acme-deliverable-templates.ttl) declare the SPARQL queries for each page section. The generator reads these via arch:sectionQuery — no hard-coded queries in the tool itself.

Queries run against the loaded RDF graph and produce tabular results:

# Generate application catalog page
PREFIX am4:  <https://meta.linked.archi/archimate4/onto#>
PREFIX acme: <https://example.com/acme/onto#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?app ?label ?team ?teamLabel ?lifecycle ?recommendation WHERE {
    ?app a am4:ApplicationComponent ;
         skos:prefLabel ?label ;
         acme:ownedBy ?team ;
         arch:lifecycleState ?lifecycle .
    ?team skos:prefLabel ?teamLabel .
    OPTIONAL {
        ?app am4:runsOn ?tech .
        ?tech acme:hasRecommendation ?rec .
        ?rec skos:prefLabel ?recommendation .
    }
}
ORDER BY ?label

Step 2: Templates Produce Markdown¶

A Handlebars template consumes the SPARQL results:

# Application Landscape

| Application | Owner | Lifecycle | Tech Recommendation |
|-------------|-------|-----------|---------------------|
{{#each results}}
| **{{label}}** | {{teamLabel}} | {{lifecycle}} | {{recommendation}} |
{{/each}}

---
*Generated from architecture knowledge graph on {{generatedDate}}.*

Step 3: Markdown Renders to Multiple Formats¶

Target	Tool	Command
HTML (browsable site)	MkDocs Material	`mkdocs build`
Confluence	markdown-to-confluence	`m2c push --space ARCH`
PDF	Pandoc + WeasyPrint	`pandoc --to=pdf`
Slides	Marp CLI	`marp --pdf catalog-overview.md`
PPTX	Pandoc	`pandoc --to=pptx`

The key: you choose the output format at deployment time, not at authoring time. The TTL is authored once. The Markdown is generated. The final format is a downstream concern.

The Build-or-Buy Decision¶

At this point you have a complete metamodel, shapes, and a generation pipeline design. The question is: what tool hosts the architecture instances?

Option Landscape¶

Approach	Examples	Pros	Cons
RDF-native repository	GraphDB, Oxigraph, Fuseki	Full SPARQL, native SHACL validation, no transformation	Steep learning curve for architects, limited visual tooling
Git + TTL files (architecture-as-code)	VS Code + Turtle extensions	Version control, diff-friendly, CI/CD native, developer workflow	No visual modeling, manual authoring friction
EA tool with RDF export	Archi (with RDF plugin), Sparx EA	Visual modeling, mature UX	Export is one-way; RDF is secondary, not source of truth
Custom tool built on the metamodel	See Build Your Own Modeling Tool	Full control, metamodel-native	Development investment, maintenance cost
Hybrid: visual tool + RDF sync	Tool → RDF export → validation → tool	Best of both worlds	Integration complexity, sync conflicts

Decision Criteria¶

Criterion	Weight	RDF-Native	Git+TTL	EA Tool+Export	Custom	Hybrid
SHACL validation integrated	High	✅	✅ (CI/CD)	❌	✅	✅
Visual modeling UX	High	❌	❌	✅	✅	✅
SPARQL query access	High	✅	✅ (load into store)	❌	✅	✅
Version control / diff	Medium	❌	✅	❌	Varies	✅
AI/MCP accessibility	Medium	✅	✅	❌	✅	✅
Architect learning curve	Medium	Hard	Medium	Easy	Easy	Medium
Multi-format generation	Medium	✅	✅	❌	✅	✅
Time to production	Low	Fast	Fast	Fast	Slow	Medium

Recommendation for ACME Corp¶

For a mid-size enterprise starting from scratch:

Start with Git + TTL (architecture-as-code) for the first 6 months. This: - Leverages existing developer workflow (PR reviews, CI/CD) - Validates the metamodel against real usage before investing in tooling - Produces immediate value via generated Markdown → MkDocs site - Defers the expensive decision (custom tool vs. vendor) until requirements are proven

Then evaluate whether to build a custom visual layer or adopt a tool with RDF export. By that point you'll know which viewpoints get the most use, which stakeholders need visual editing, and whether the Git workflow scales.

See Build Your Own Modeling Tool for the full implementation guide if you choose the custom path.

AI Accessibility via MCP¶

A metamodel expressed in RDF is inherently AI-ready. The Model Context Protocol (MCP) provides the bridge:

What MCP Enables¶

Capability	How It Works
Query architecture	AI agent sends SPARQL via MCP → gets structured results
Validate proposals	Agent proposes a change → SHACL validation runs → violations reported
Generate views	Agent requests a viewpoint rendering → SPARQL + template → Markdown returned
Impact analysis	"What depends on this application?" → traversal query → dependency list
Governance check	"Is this initiative compliant?" → run compliance queries → report gaps

Architecture¶

┌─────────────┐     ┌─────────────────┐     ┌──────────────────┐
│  AI Agent   │────▶│  MCP Server     │────▶│  RDF Graph       │
│ (Kiro, etc.)│     │                 │     │  (architecture   │
│             │◀────│ • query tool    │◀────│   knowledge)     │
│             │     │ • validate tool │     │                  │
│             │     │ • generate tool │     │ • acme-model.ttl │
│             │     │                 │     │ • acme-onto.ttl  │
└─────────────┘     └─────────────────┘     └──────────────────┘

This means architects can ask natural-language questions ("which applications handle personal data without a legal basis?") and get answers backed by the validated knowledge graph — not hallucinated from training data.

Connecting the Worked Example¶

The ACME Corp catalog (currently static HTML in examples/acme-corp/) becomes generated output:

Current State (Parts 1–4)	Target State (Part 7)
Hand-authored `index.html`	Generated from `acme-deliverable-templates.ttl` → SPARQL on model data
Hardcoded artifact tables	`arch:sectionQuery` results → Handlebars → Markdown → HTML
Static viewpoint cards	Viewpoint definitions from `acme-viewpoints.ttl` rendered via template
Manual governance metadata	`dcterms:modified`, `arch:lifecycleState` queried from the graph

The static HTML prototype served its purpose — validating the structure and content. With the TTL files from Part 5 and shapes from Part 6 in place, the generation pipeline can now produce the same output (and keep it current) from the single source of truth.

Implementation Roadmap for ACME Corp¶

Week	Activity	Outcome
1	Load TTL into Oxigraph/Fuseki	Queryable graph endpoint
2	Write SPARQL queries for each catalog page	Data extraction validated
3	Build Handlebars templates	Markdown generation working
4	Wire MkDocs build	Browsable HTML from generated Markdown
5	Add SHACL validation to CI	Governance automation active
6	Deploy MCP server	AI agents can query the graph

Practical Tips¶

Do¶

Generate, don't copy. If a fact lives in the graph, query it. Don't copy it into a document that will go stale.
Keep templates simple. A template should be < 50 lines. If it's complex, your SPARQL query isn't structured correctly.
Version the pipeline alongside the metamodel. A metamodel change (new property) usually requires a template update (new column). Keep them in the same repo.
Start with one viewpoint. Get the Application Landscape generating perfectly before tackling all five viewpoints.

Don't¶

Don't build a tool before validating the metamodel. The first 6 months should prove the metamodel works with real architecture data. A premature tool locks in assumptions.
Don't over-engineer the pipeline. A shell script that runs SPARQL, pipes through Handlebars, and outputs Markdown is enough to start. Sophistication comes from real usage feedback.
Don't forget the human loop. Not everything should be automated. Architecture decisions, maturity assessments, and strategic prioritization require human judgment — the tool supports them, not replaces them.

Series Conclusion¶

This series took you from zero — no metamodel, no governance, no tooling — to a fully specified architecture practice:

Part	What You Produced	Audience
1	Stakeholder register, viewpoint candidates	Business + architecture
2	Structured viewpoint catalog, artifact register	Architecture + governance
3	Conceptual metamodel, design decisions	Architecture
4	Governance handbook, RACI, cadences	Governance + management
5	OWL ontology, SKOS taxonomy, manifest	Ontology engineering
6	SHACL shapes, SPARQL queries, CI/CD	Engineering + DevOps
7	Generation pipeline, tool integration	Platform + engineering

The practice is: - Open — standard RDF, no vendor lock-in - Interoperable — SPARQL-queryable, linkable, composable with other graphs - Governed — SHACL-validated, cadence-driven, ownership-clear - AI-ready — MCP-accessible, machine-readable, semantically typed - Evolvable — semantic versioning, additive changes, deprecation paths

Start narrow (5 viewpoints, 12 artifacts), validate against reality, and extend based on demand.

References¶

Build Your Own Modeling Tool — full implementation guide for the "build" path
Build Your Own Metamodel — metamodel pattern reference
Deliverable Templates Guide — Handlebars template patterns
Generator Spec — SPARQL → Markdown generation specification
Semantic Architecture as Code — the Git + TTL workflow
Part 5 — Formal Metamodel Definition
Part 6 — Formal Governance & Validation

This concludes the Architecture Practice from Scratch series. For questions, feedback, or contributions, see the series introduction.