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. The instance data they operate against lives in acme-model.ttl. Browse all assets from the ACME Corp Artifact Catalog.
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 |
| 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 modelling, manual authoring friction |
| EA tool with RDF export | Archi (with RDF plugin), Sparx EA | Visual modelling, 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 modelling 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.
The custom-tool caveat. With AI, "build" is now cheap enough that teams reach for it by default — and a bespoke tool that stores knowledge in its own shape is just a new silo, needing the same integration a vendor tool would. Before choosing (or building) a custom tool, apply the five-question test in Interoperability by Design: shared vocabulary, resolvable identity, lossless RDF serialization, a shared SHACL contract, and open query access.
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 catalogue (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.
Who Operates This?¶
The pipeline, the repository, the SHACL validation, and the MCP server do not run themselves. Everything in this part is the standing responsibility of the Architecture Enablement function introduced in Part 4 (iso42020:ArchitectureEnablement, TOGAF's Architecture Capability). This is where "who owns the means of architecture" becomes concrete: the enablement team operates the platform, architects consume its outputs, and governance bodies receive the reports it generates.
The enablement team runs the platform as an internal product. Architects get generated docs and query access; governance bodies get compliance reports — all from the single TTL source of truth.
The roadmap below is, in effect, the enablement team's initial backlog:
- Weeks 1–2 (load graph, write SPARQL) exercise
iso42020:ArchitectureConceptualizationfeedback — proving the metamodel against real queries. - Weeks 3–4 (templates, MkDocs) stand up the generation pipeline that keeps every deliverable current from source.
- Week 5 (SHACL in CI) wires the Part 6 governance gates into the pipeline.
- Week 6 (MCP server) opens AI access to the graph.
Ongoing, this function also owns metamodel evolution (the change process in Part 4), so the pipeline and shapes stay aligned with the schema as it changes. Without a named owner, the pipeline silently breaks the first time the metamodel moves.
Implementation Roadmap for ACME Corp¶
| Week | Activity | Outcome |
|---|---|---|
| 1 | Load TTL into Oxigraph/Fuseki | Queryable graph endpoint |
| 2 | Write SPARQL queries for each catalogue 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 catalogue, 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
- Architecture Decision Ontology — used for the Payment Platform decision record
- Technology Radar Ontology — governs technology adoption in the Standards viewpoint
- Part 4 — Governance & Lifecycle Management — defines the Architecture Enablement function that operates this pipeline
- Part 5 — Formal Metamodel Definition
- Part 6 — Formal Governance & Validation
Worked Example: Browse the ACME Corp Artifact Catalog to see the concepts from this series applied to a fictional mid-size enterprise.
This concludes the Architecture Practice from Scratch series. For questions, feedback, or contributions, see the series introduction.