Deliverable Generator — Tool Specification

Overview

The Deliverable Generator is a command-line tool that produces architecture documents from the Linked.Archi knowledge graph. It reads arch:DeliverableTemplate definitions from the ontology, executes the SPARQL queries declared on each arch:TemplateSection, and renders the results through Handlebars templates into Markdown, HTML, or PDF output.

The entire pipeline is declarative: the ontology defines what data to extract (arch:sectionQuery), how to structure it (arch:sectionResultKey, arch:sectionOrder), and how to render it (arch:templateResource). The tool itself contains no domain-specific logic.

Architecture

┌─────────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Knowledge Graph     │     │  Ontology         │     │  Template Files  │
│  (model data in      │     │  (deliverable     │     │  (.md.hbs)       │
│   triplestore)       │     │   template defs)  │     │                  │
└────────┬────────────┘     └────────┬─────────┘     └────────┬────────┘
         │                           │                         │
         │  SPARQL queries           │  section definitions    │  Handlebars
         │  from arch:sectionQuery   │  arch:sectionOrder      │  templates
         │                           │  arch:sectionResultKey  │
         ▼                           ▼                         ▼
┌────────────────────────────────────────────────────────────────────────┐
│                      Deliverable Generator                             │
│                                                                        │
│  1. Load template definition (from ontology or TTL file)               │
│  2. Discover sections (arch:templateHasSection), sort by sectionOrder  │
│  3. For each section: execute arch:sectionQuery against SPARQL endpoint│
│  4. Assemble JSON context: { meta: {...}, [resultKey]: [...], ... }    │
│  5. Render arch:templateResource with Handlebars                       │
│  6. Write output file                                                  │
└────────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────┐
│  Output              │
│  architecture-       │
│  definition-doc.md   │
└─────────────────────┘

CLI Interface

# Generate from a template defined in the ontology
la-generate \
  --template https://meta.linked.archi/archimate3/deliverable-templates#ArchitectureDefinitionDocument \
  --endpoint http://localhost:7200/repositories/my-architecture \
  --output architecture-definition-document.md

# Generate from a local TTL file (offline mode)
la-generate \
  --template-file modelingLanguages/archimate/3.2/archimate3.2-deliverable-templates.ttl \
  --template-id ArchitectureDefinitionDocument \
  --data-files "core/core-onto.ttl,modelingLanguages/archimate/3.2/archimate3.2-onto.ttl,my-model.ttl" \
  --output architecture-definition-document.md

# Override metadata
la-generate \
  --template-file ... \
  --meta '{"author":"Kalin Maldzhanski","date":"2026-04-24","status":"Draft","version":"1.0"}' \
  --output ...

Processing Pipeline

Step 1: Load Template Definition

The tool loads the arch:DeliverableTemplate individual either from a SPARQL endpoint or a local TTL file. It extracts:

• skos:prefLabel — document title
• skos:definition — document description (used in meta.description)
• arch:templateResource — path to the Handlebars template file
• arch:templateHasSection — list of arch:TemplateSection individuals

Step 2: Discover and Order Sections

For each arch:TemplateSection, the tool reads:

• arch:sectionOrder — integer for sorting
• arch:sectionResultKey — JSON key for the query results
• arch:sectionQuery — the SPARQL SELECT query
• skos:prefLabel — section heading
• skos:definition — section description

Sections are sorted by arch:sectionOrder ascending.

Step 3: Execute Queries

For each section, the tool executes arch:sectionQuery against the SPARQL endpoint (or in-memory graph for offline mode). The SELECT results are converted to a JSON array of objects where each variable becomes a key:

SELECT ?label ?description ?assignedTo WHERE { ... }

Becomes:

[
  { "label": "IT Operations", "description": "Manages infrastructure", "assignedTo": "CTO" },
  { "label": "Customer Service", "description": "Handles inquiries", "assignedTo": null }
]

Step 4: Assemble Context

The tool builds a single JSON context object:

{
  "meta": {
    "title": "Architecture Definition Document",
    "date": "2026-04-24",
    "author": "Kalin Maldzhanski",
    "status": "Draft",
    "version": "1.0",
    "description": "The primary ArchiMate deliverable..."
  },
  "sections": [
    {
      "order": 1,
      "title": "1. Business Organization",
      "description": "Organizational structure — actors, roles, collaborations.",
      "resultKey": "businessOrganization"
    }
  ],
  "businessOrganization": [
    { "element": "...", "label": "IT Operations", "type": "BusinessActor", "description": "..." }
  ],
  "businessProcessCooperation": [ ... ],
  "applicationCooperation": [ ... ],
  "technologyInfrastructure": [ ... ],
  "crossLayerOverview": [ ... ],
  "implementationDeployment": [ ... ]
}

Step 5: Render Template

The Handlebars template file (from arch:templateResource) is rendered with the assembled context. The template uses {{#each businessOrganization}} to iterate over section results.

Step 6: Write Output

The rendered Markdown is written to the output path. For PDF output, the tool pipes through a Markdown-to-PDF converter (e.g., Pandoc, WeasyPrint).

Configuration

# la-generate.yml (optional config file)
defaults:
  endpoint: http://localhost:7200/repositories/architecture
  templateBase: modelingLanguages/archimate/3.2/
  outputDir: deliverables/
  meta:
    author: "Architecture Team"
    status: "Draft"

Dependencies

• Runtime: Node.js 18+ or Python 3.10+
• SPARQL: Any SPARQL 1.1 endpoint (Oxigraph, Fuseki, GraphDB) or in-memory via rdflib/Oxigraph embedded
• Templating: Handlebars (Node.js) or pybars3 (Python)
• PDF (optional): Pandoc or WeasyPrint

Error Handling

• If a section's arch:sectionQuery returns zero results, the section is rendered with an empty table and a note: "No elements found for this section."
• If arch:sectionQuery is missing from a section, the tool logs a warning and renders the section header and description only (no data table).
• If the SPARQL endpoint is unreachable, the tool exits with a clear error message.
• SPARQL syntax errors in arch:sectionQuery are reported with the section label and query text for debugging.

Future Extensions

• CONSTRUCT queries: Support arch:sectionQuery with CONSTRUCT for richer graph-shaped results (e.g., nested elements with their relationships).
• Parameterized queries: Support $model or $view placeholders in queries that the tool substitutes with the target model/view IRI.
• Multi-format: Read arch:templateHasFormat and generate all supported formats in one run.
• Diagram generation: For sections with arch:sectionViewpoint, auto-generate SVG diagrams from the query results using a layout engine.
• Watch mode: Re-generate when the knowledge graph changes (via SPARQL UPDATE notifications or file watchers).