arc42 and ArchiMate examples: nine models, three per framework; 1.2
The six models from extension 0.11.0 (arc42 by section, ArchiMate by layer) next to the three C4 ones; model:scaffold --example offers them and the tests validate each with 0 problems.
This commit is contained in:
1 parent
21770c241d
commit
d9777fb90e
74 files changed
+2768
-7
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.
|
||||
+20
@@ -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.
|
||||
Reference in new issue
Block a user