0.11.0: arc42 and ArchiMate examples; ref in every diagram kind

Six example models next to the three C4 ones: arc42 (Cinema Tickets, IoT
Telemetry, Team Wiki) by section, ArchiMate (Insurance Claims, HR
Onboarding, Logistics Tracking) by layer, each validated with 0 errors and
0 warnings. resolveRefs and the editor schemas now take ref: in workflow
and dataflow nodes, sequence participants and lifecycle states, as the
skill already did. Example tests check each framework's folders.
This commit is contained in:
root-at-skic committed 2026-11-08 22:54:23 +02:00
1 parent f4df6a0834
commit 0745de822a
85 files changed
+2945 -67

No files matched your search

@@ -0,0 +1,35 @@
schema_version: 1
diagram_type: architecture
meta:
title: Technical context
output: technical-context.html
decisions: [mqtt-with-mutual-tls]
components:
- ref: homeowner
pos: [40, 60]
size: [130, 60]
- ref: ops-engineer
pos: [40, 160]
size: [130, 60]
- ref: installer
pos: [40, 260]
size: [130, 60]
- ref: telemetry-platform
pos: [280, 160]
size: [150, 60]
- ref: heat-pump
pos: [540, 60]
size: [130, 60]
- ref: push-service
pos: [540, 160]
size: [130, 60]
- ref: service-desk
pos: [540, 260]
size: [130, 60]
connections:
- { from: homeowner, to: telemetry-platform, label: HTTPS }
- { from: ops-engineer, to: telemetry-platform, label: HTTPS, variant: security }
- { from: installer, to: telemetry-platform, label: HTTPS }
- { from: heat-pump, to: telemetry-platform, label: MQTT 8883, variant: emphasis, decisions: [mqtt-with-mutual-tls] }
- { from: telemetry-platform, to: push-service, label: HTTP/2 }
- { from: telemetry-platform, to: service-desk, label: webhook }
@@ -0,0 +1,50 @@
schema_version: 1
diagram_type: architecture
meta:
title: Ingest, level 2
output: ingest.html
components:
- ref: mqtt-broker
pos: [40, 160]
size: [130, 60]
- id: decoder
type: backend
label: Decoder
sublabel: payload v1, v2
pos: [250, 160]
size: [130, 60]
- id: validator
type: backend
label: Validator
sublabel: ranges, clock
pos: [460, 160]
size: [130, 60]
- id: writer
type: backend
label: Batch writer
sublabel: 500 rows
pos: [670, 160]
size: [130, 60]
- id: dead-letter
type: database
label: Dead letters
sublabel: rejected readings
pos: [460, 310]
size: [130, 60]
- ref: tsdb
pos: [880, 160]
size: [130, 60]
- ref: rules
pos: [670, 310]
size: [130, 60]
boundaries:
- kind: region
label: Ingest
wraps: [decoder, validator, writer, dead-letter]
connections:
- { from: mqtt-broker, to: decoder, label: messages, variant: emphasis }
- { from: decoder, to: validator, label: readings, variant: emphasis }
- { from: validator, to: writer, label: valid, variant: emphasis }
- { from: validator, to: dead-letter, label: invalid, variant: dashed, labelAt: [525, 234] }
- { from: writer, to: tsdb, label: COPY, variant: emphasis }
- { from: writer, to: rules, label: stream, labelAt: [735, 234] }
@@ -0,0 +1,77 @@
schema_version: 1
diagram_type: architecture
meta:
title: Building blocks, level 1
output: level-1.html
decisions: [timescaledb-for-telemetry]
components:
- ref: heat-pump
pos: [40, 160]
size: [130, 60]
- ref: installer
pos: [40, 360]
size: [130, 60]
- ref: mqtt-broker
pos: [250, 160]
size: [130, 60]
decisions: [mqtt-with-mutual-tls]
- ref: provisioning
pos: [250, 360]
size: [130, 60]
- ref: rules
pos: [460, 60]
size: [130, 60]
- ref: ingest
pos: [460, 160]
size: [130, 60]
- ref: device-registry
pos: [460, 360]
size: [130, 60]
- ref: tsdb
pos: [670, 160]
size: [130, 60]
- ref: device-api
pos: [670, 360]
size: [130, 60]
- ref: ops-dashboard
pos: [880, 160]
size: [130, 60]
- ref: customer-app
pos: [880, 360]
size: [130, 60]
- ref: push-service
pos: [1090, 60]
size: [130, 60]
- ref: ops-engineer
pos: [1090, 160]
size: [130, 60]
- ref: homeowner
pos: [1090, 360]
size: [130, 60]
boundaries:
- kind: region
label: IoT Telemetry
wraps: [mqtt-broker, provisioning, rules, ingest, device-registry, tsdb, device-api, ops-dashboard, customer-app]
connections:
- { from: heat-pump, to: mqtt-broker, label: publish, variant: emphasis, decisions: [mqtt-with-mutual-tls] }
- { from: mqtt-broker, to: ingest, label: subscribe, variant: emphasis }
- { from: ingest, to: tsdb, label: write, variant: emphasis }
- { from: ingest, to: rules, label: stream }
- { from: ingest, to: device-registry, label: lookup, labelAt: [525, 234] }
- { from: rules, to: push-service, label: alert }
- { from: installer, to: provisioning, label: register }
- { from: provisioning, to: mqtt-broker, label: certs, variant: security }
- { from: provisioning, to: device-registry, label: store }
- { from: device-api, to: tsdb, label: read }
- { from: device-api, to: device-registry, label: read }
- { from: tsdb, to: ops-dashboard, label: query }
- { from: customer-app, to: device-api, label: REST }
- { from: ops-engineer, to: ops-dashboard, label: views }
- { from: homeowner, to: customer-app, label: uses }
cards:
- dot: amber
title: 8 Crosscutting concepts
items:
- Device identity, one X.509 certificate per device
- Idempotent writes, keyed by device id and timestamp
- Observability, metrics and traces on every service
@@ -0,0 +1,20 @@
schema_version: 1
diagram_type: sequence
meta:
title: Device provisioning
output: device-provisioning.html
decisions: [mqtt-with-mutual-tls]
participants:
- { ref: installer }
- { ref: provisioning }
- { ref: device-registry, label: Devices }
- { ref: heat-pump }
- { ref: mqtt-broker }
messages:
- { from: installer, to: provisioning, y: 160, label: register serial, variant: emphasis }
- { from: provisioning, to: device-registry, y: 210, label: store device }
- { from: provisioning, to: installer, y: 260, label: certificate, variant: return }
- { from: installer, to: heat-pump, y: 310, label: load certificate }
- { from: heat-pump, to: mqtt-broker, y: 360, label: connect mTLS, variant: emphasis }
- { from: mqtt-broker, to: provisioning, y: 410, label: check revocation }
- { from: mqtt-broker, to: heat-pump, y: 460, label: CONNACK, variant: return }
@@ -0,0 +1,20 @@
schema_version: 1
diagram_type: sequence
meta:
title: Fault reading to alert
output: telemetry-to-alert.html
participants:
- { ref: heat-pump }
- { ref: mqtt-broker }
- { ref: ingest }
- { ref: tsdb, label: TSDB }
- { ref: rules }
- { ref: push-service }
messages:
- { from: heat-pump, to: mqtt-broker, y: 160, label: publish fault, variant: emphasis }
- { from: mqtt-broker, to: ingest, y: 210, label: deliver QoS 1 }
- { from: ingest, to: tsdb, y: 260, label: write batch }
- { from: tsdb, to: ingest, y: 310, label: committed, variant: return }
- { from: ingest, to: mqtt-broker, y: 360, label: ack, variant: return }
- { from: ingest, to: rules, y: 410, label: reading }
- { from: rules, to: push-service, y: 460, label: send alert, variant: emphasis }
@@ -0,0 +1,44 @@
schema_version: 1
diagram_type: architecture
meta:
title: Deployment, production
output: production.html
decisions: [timescaledb-for-telemetry]
components:
- ref: heat-pump
pos: [40, 160]
size: [130, 60]
- ref: mqtt-broker
pos: [280, 160]
size: [130, 60]
- ref: ingest
pos: [490, 160]
size: [130, 60]
- ref: rules
pos: [490, 60]
size: [130, 60]
- ref: provisioning
pos: [280, 260]
size: [130, 60]
- ref: device-api
pos: [490, 260]
size: [130, 60]
- ref: tsdb
pos: [760, 160]
size: [130, 60]
- ref: device-registry
pos: [760, 260]
size: [130, 60]
boundaries:
- kind: region
label: Kubernetes cluster, eu-central
wraps: [mqtt-broker, ingest, rules, provisioning, device-api]
- kind: security-group
label: Managed DB zone
wraps: [tsdb, device-registry]
connections:
- { from: heat-pump, to: mqtt-broker, label: "8883", variant: emphasis }
- { from: mqtt-broker, to: ingest, label: in-cluster }
- { from: ingest, to: tsdb, label: "5432", variant: emphasis }
- { from: ingest, to: rules, label: gRPC }
- { from: device-api, to: device-registry, label: "5432" }
@@ -0,0 +1,21 @@
schema_version: 1
decision:
id: mqtt-with-mutual-tls
title: MQTT with mutual TLS for device traffic
status: accepted
date: 2026-08-12
elements: [heat-pump, mqtt-broker, provisioning]
diagrams: [0300-context/technical-context.archify, 0500-building-blocks/level-1.archify]
context: >
Heat pumps sit behind home routers on slow and flaky links.
The first prototype polled an HTTPS endpoint and drained
mobile data plans; shared API keys leaked from one device.
decision: >
Devices publish over MQTT 3.1.1 on port 8883. Each device
has its own client certificate issued by Provisioning;
the broker rejects any connection without one.
consequences: >
Small messages and one long-lived connection per device.
Certificates must be rotated and revoked, so Provisioning
is a critical building block. Installers need a step to
register the device before it can connect.
@@ -0,0 +1,20 @@
schema_version: 1
decision:
id: timescaledb-for-telemetry
title: TimescaleDB for telemetry
status: accepted
date: 2026-09-03
elements: [tsdb, ingest, ops-dashboard]
diagrams: [0500-building-blocks/level-1.archify, 0700-deployment/production.archify]
context: >
The fleet sends about 4,000 readings a second. A plain
PostgreSQL table grew too fast and dashboards slowed down
after a few weeks of data.
decision: >
Store telemetry in TimescaleDB hypertables with hourly
continuous aggregates. Raw data is kept 90 days, rollups
10 years. The team already runs PostgreSQL.
consequences: >
SQL stays the query language for the API and the
dashboard. Retention jobs must be monitored. Very high
device counts may need sharding later (see risk R1).
@@ -0,0 +1,76 @@
schema_version: 1
model:
id: iot-telemetry
name: IoT Telemetry
description: >
An arc42 example: a fictional heat pump maker collects device telemetry
over MQTT, stores it, raises alerts and shows it to operations and customers.
main.archify holds section 3 business context with cards for sections
1 goals, 2 constraints, 10 quality, 11 risks and 12 glossary;
0300-context the technical context; 0500-building-blocks section 5;
0600-runtime section 6; 0700-deployment section 7; decisions/ section 9;
the crosscutting concepts of section 8 are a card on level-1.
diagram_type: architecture
meta:
title: Business context
output: main.html
components:
- ref: homeowner
pos: [40, 60]
size: [130, 60]
- ref: ops-engineer
pos: [40, 160]
size: [130, 60]
- ref: installer
pos: [40, 260]
size: [130, 60]
- ref: telemetry-platform
pos: [280, 160]
size: [150, 60]
- ref: heat-pump
pos: [540, 60]
size: [130, 60]
- ref: push-service
pos: [540, 160]
size: [130, 60]
- ref: service-desk
pos: [540, 260]
size: [130, 60]
connections:
- { from: homeowner, to: telemetry-platform, label: checks }
- { from: ops-engineer, to: telemetry-platform, label: monitors }
- { from: installer, to: telemetry-platform, label: registers }
- { from: heat-pump, to: telemetry-platform, label: telemetry, variant: emphasis }
- { from: telemetry-platform, to: push-service, label: alerts }
- { from: telemetry-platform, to: service-desk, label: tickets }
cards:
- dot: cyan
title: 1 Quality goals
items:
- Reliability, no telemetry lost once accepted
- Timeliness, alert within 60 s of a fault
- Security, every device authenticated
- dot: slate
title: 2 Constraints
items:
- Devices speak MQTT only; firmware by a partner
- Data stays in one EU region
- Team of six; PostgreSQL skills in house
- dot: emerald
title: 10 Quality scenarios
items:
- A fault code reaches the homeowner within 60 s
- Broker restart, devices reconnect, no data lost
- A stolen certificate is revoked within 15 min
- dot: rose
title: 11 Risks
items:
- R1 fleet growth beyond one TSDB node
- R2 partner firmware delays certificate rotation
- dot: violet
title: 12 Glossary
items:
- Telemetry, readings a device sends
- Rollup, hourly aggregate of telemetry
- Provisioning, giving a device its identity
- Fault code, error number from the device
@@ -0,0 +1,61 @@
schema_version: 1
elements:
mqtt-broker:
type: messagebus
label: MQTT broker
sublabel: mutual TLS
description: >
Terminates device connections; one topic per device.
ingest:
type: backend
label: Ingest
sublabel: Go
brand: go
description: >
Decodes, validates and stores telemetry; forwards it to the rules.
diagram: 0500-building-blocks/ingest.archify
tsdb:
type: database
label: Time series DB
sublabel: TimescaleDB
brand: postgresql
description: >
Raw telemetry for 90 days and hourly rollups for 10 years.
rules:
type: backend
label: Rules engine
sublabel: alerting
description: >
Evaluates thresholds and fault codes; raises alerts.
provisioning:
type: security
label: Provisioning
sublabel: device certs
description: >
Registers devices and issues their client certificates.
device-registry:
type: database
label: Device registry
sublabel: PostgreSQL
brand: postgresql
description: >
Devices, owners, firmware versions and certificate state.
device-api:
type: backend
label: Device API
sublabel: REST
description: >
Serves telemetry and device data to the customer app.
ops-dashboard:
type: frontend
label: Ops dashboard
sublabel: Grafana
brand: grafana
description: >
Fleet view for the operations team, read only on the TSDB.
customer-app:
type: frontend
label: Customer app
sublabel: mobile
description: >
Shows the homeowner their heat pump and its alerts.
@@ -0,0 +1,20 @@
schema_version: 1
elements:
homeowner:
type: external
label: Homeowner
sublabel: customer app
description: >
Owns a heat pump; checks temperatures and gets fault alerts.
ops-engineer:
type: external
label: Ops engineer
sublabel: operations team
description: >
Watches the fleet, handles alerts and plans service visits.
installer:
type: external
label: Installer
sublabel: field service
description: >
Mounts heat pumps on site and registers them with the platform.
@@ -0,0 +1,27 @@
schema_version: 1
elements:
telemetry-platform:
type: cloud
label: IoT Telemetry
sublabel: the system
description: >
Everything we build and run; broker, ingest, stores, rules and apps.
diagram: 0500-building-blocks/level-1.archify
heat-pump:
type: external
label: Heat pump
sublabel: field device
description: >
Sends telemetry every 30 seconds over MQTT; built by a partner.
push-service:
type: external
label: Push service
sublabel: mobile push
description: >
Delivers push notifications to the customer app.
service-desk:
type: external
label: Service desk
sublabel: ticketing
description: >
Opens service tickets for faults that need a visit.