0.11.1: the arc42 examples cover all twelve sections
Numbered cards for the text sections (1.1-1.3, 2, 4, 11, 12) on the overview, domain interfaces on the technical context, black-box descriptions for every building block, blocks mapped to nodes in the deployment view, crosscutting concepts on level 1, and a 1000-quality folder with the quality tree. The example test checks each section's card.
This commit is contained in:
1 parent
2ab4287f02
commit
f4663c089d
23 files changed
+511
-91
No files matched your search
@@ -33,3 +33,13 @@ connections:
|
||||
- { 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 }
|
||||
cards:
|
||||
- dot: cyan
|
||||
title: 3 Domain interfaces
|
||||
items:
|
||||
- "Heat pump: in telemetry and fault codes; out none"
|
||||
- "Homeowner: in app requests; out status, history, alerts"
|
||||
- "Ops engineer: in queries; out fleet dashboards"
|
||||
- "Installer: in device serial; out device certificate"
|
||||
- "Push service: out alert notifications"
|
||||
- "Service desk: out tickets for faults needing a visit"
|
||||
@@ -73,5 +73,8 @@ cards:
|
||||
title: 8 Crosscutting concepts
|
||||
items:
|
||||
- Device identity, one X.509 certificate per device
|
||||
- Security, OIDC login for people, mTLS for devices
|
||||
- Persistence, PostgreSQL dialect for all stores
|
||||
- Idempotent writes, keyed by device id and timestamp
|
||||
- Error handling, invalid readings to dead letters
|
||||
- Observability, metrics and traces on every service
|
||||
@@ -29,6 +29,12 @@ components:
|
||||
- ref: device-registry
|
||||
pos: [760, 260]
|
||||
size: [130, 60]
|
||||
- ref: ops-dashboard
|
||||
pos: [1030, 160]
|
||||
size: [130, 60]
|
||||
- ref: customer-app
|
||||
pos: [490, 440]
|
||||
size: [130, 60]
|
||||
boundaries:
|
||||
- kind: region
|
||||
label: Kubernetes cluster, eu-central
|
||||
@@ -36,9 +42,26 @@ boundaries:
|
||||
- kind: security-group
|
||||
label: Managed DB zone
|
||||
wraps: [tsdb, device-registry]
|
||||
- kind: region
|
||||
label: Ops network, managed Grafana
|
||||
wraps: [ops-dashboard]
|
||||
- kind: region
|
||||
label: Homeowner phones
|
||||
wraps: [customer-app]
|
||||
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" }
|
||||
- { from: tsdb, to: ops-dashboard, label: read-only }
|
||||
- { from: customer-app, to: device-api, label: HTTPS }
|
||||
cards:
|
||||
- dot: slate
|
||||
title: 7 Mapping
|
||||
items:
|
||||
- "mqtt-broker, ingest, rules -> Kubernetes cluster, eu-central"
|
||||
- "provisioning, device-api -> Kubernetes cluster, eu-central"
|
||||
- "tsdb, device-registry -> managed DB zone, eu-central"
|
||||
- "ops-dashboard -> ops network, managed Grafana"
|
||||
- "customer-app -> homeowner phones, app stores"
|
||||
@@ -0,0 +1,75 @@
|
||||
schema_version: 1
|
||||
diagram_type: architecture
|
||||
meta:
|
||||
title: Quality tree
|
||||
output: quality-tree.html
|
||||
components:
|
||||
- id: quality
|
||||
type: cloud
|
||||
label: Quality
|
||||
pos: [40, 240]
|
||||
size: [130, 100]
|
||||
- id: reliability
|
||||
type: backend
|
||||
label: Reliability
|
||||
pos: [250, 60]
|
||||
size: [130, 60]
|
||||
- id: performance
|
||||
type: backend
|
||||
label: Performance
|
||||
pos: [250, 210]
|
||||
size: [130, 60]
|
||||
- id: security
|
||||
type: security
|
||||
label: Security
|
||||
pos: [250, 360]
|
||||
size: [130, 60]
|
||||
- id: operability
|
||||
type: backend
|
||||
label: Operability
|
||||
pos: [250, 460]
|
||||
size: [130, 60]
|
||||
- id: q-no-loss
|
||||
type: frontend
|
||||
label: Broker restart, no loss
|
||||
pos: [460, 60]
|
||||
size: [180, 60]
|
||||
- id: q-alert-60s
|
||||
type: frontend
|
||||
label: Fault alert in 60 s
|
||||
pos: [460, 160]
|
||||
size: [180, 60]
|
||||
- id: q-peak-load
|
||||
type: frontend
|
||||
label: 4,000 readings/s
|
||||
pos: [460, 260]
|
||||
size: [180, 60]
|
||||
- id: q-revoke
|
||||
type: frontend
|
||||
label: Revoke cert in 15 min
|
||||
pos: [460, 360]
|
||||
size: [180, 60]
|
||||
- id: q-new-device
|
||||
type: frontend
|
||||
label: New device in 10 min
|
||||
pos: [460, 460]
|
||||
size: [180, 60]
|
||||
connections:
|
||||
- { from: quality, to: reliability }
|
||||
- { from: quality, to: performance }
|
||||
- { from: quality, to: security }
|
||||
- { from: quality, to: operability }
|
||||
- { from: reliability, to: q-no-loss }
|
||||
- { from: performance, to: q-alert-60s }
|
||||
- { from: performance, to: q-peak-load }
|
||||
- { from: security, to: q-revoke }
|
||||
- { from: operability, to: q-new-device }
|
||||
cards:
|
||||
- dot: emerald
|
||||
title: 10 Quality scenarios
|
||||
items:
|
||||
- "Broker restarts under load: devices reconnect, no accepted reading lost"
|
||||
- "Heat pump sends a fault code: homeowner gets a push within 60 s"
|
||||
- "Fleet peaks at 4,000 readings/s: p95 ingest lag stays under 5 s"
|
||||
- "A device certificate is stolen: ops revoke it, broker refuses it within 15 min"
|
||||
- "Installer registers a new heat pump: data visible in the app within 10 min"
|
||||
@@ -5,11 +5,14 @@ model:
|
||||
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.
|
||||
Where the 12 arc42 sections live:
|
||||
1 introduction and goals, 2 constraints, 4 solution strategy,
|
||||
11 risks and 12 glossary are cards on this overview;
|
||||
3 business context is this overview, technical context in 0300-context;
|
||||
5 building blocks in 0500-building-blocks (black boxes in the registry);
|
||||
6 runtime in 0600-runtime; 7 deployment in 0700-deployment;
|
||||
8 crosscutting concepts a card on 0500-building-blocks/level-1;
|
||||
9 decisions in decisions/; 10 quality tree in 1000-quality.
|
||||
diagram_type: architecture
|
||||
meta:
|
||||
title: Business context
|
||||
@@ -44,29 +47,47 @@ connections:
|
||||
- { from: telemetry-platform, to: push-service, label: alerts }
|
||||
- { from: telemetry-platform, to: service-desk, label: tickets }
|
||||
cards:
|
||||
- dot: orange
|
||||
title: 1.1 Requirements
|
||||
items:
|
||||
- Collect telemetry from every heat pump every 30 s
|
||||
- Alert homeowner and ops on fault codes
|
||||
- Show live and historic data in app and dashboard
|
||||
- Register and provision new devices on site
|
||||
- dot: cyan
|
||||
title: 1 Quality goals
|
||||
title: 1.2 Quality goals
|
||||
items:
|
||||
- Reliability, no telemetry lost once accepted
|
||||
- Timeliness, alert within 60 s of a fault
|
||||
- Security, every device authenticated
|
||||
- dot: emerald
|
||||
title: 1.3 Stakeholders
|
||||
items:
|
||||
- "Homeowner: sees status, gets alerts quickly"
|
||||
- "Ops engineer: fleet view, few false alarms"
|
||||
- "Installer: register a device in minutes"
|
||||
- "Firmware partner: stable MQTT contract"
|
||||
- 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
|
||||
- dot: amber
|
||||
title: 4 Solution strategy
|
||||
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
|
||||
- MQTT with mutual TLS for devices (security, ADR 0001)
|
||||
- TimescaleDB for telemetry, SQL everywhere (ADR 0002)
|
||||
- Ingest acks only after commit (reliability)
|
||||
- Rules engine on the ingest stream (timeliness)
|
||||
- Split by flow, ingest vs read vs provisioning
|
||||
- dot: rose
|
||||
title: 11 Risks
|
||||
title: 11 Risks and technical debt
|
||||
items:
|
||||
- R1 fleet growth beyond one TSDB node
|
||||
- R2 partner firmware delays certificate rotation
|
||||
- "Risk: fleet growth beyond one TSDB node"
|
||||
- "Risk: partner firmware delays cert rotation"
|
||||
- "Debt: payload v1 decoder kept for old firmware"
|
||||
- "Debt: rules configured in code, no UI"
|
||||
- dot: violet
|
||||
title: 12 Glossary
|
||||
items:
|
||||
|
||||
@@ -5,14 +5,18 @@ elements:
|
||||
label: MQTT broker
|
||||
sublabel: mutual TLS
|
||||
description: >
|
||||
Terminates device connections; one topic per device.
|
||||
Responsibility: terminates device connections, one topic per device.
|
||||
Interfaces: provides MQTT 8883 with mTLS; requires certs and
|
||||
revocation checks from Provisioning.
|
||||
ingest:
|
||||
type: backend
|
||||
label: Ingest
|
||||
sublabel: Go
|
||||
brand: go
|
||||
description: >
|
||||
Decodes, validates and stores telemetry; forwards it to the rules.
|
||||
Responsibility: decodes, validates and stores telemetry.
|
||||
Interfaces: requires MQTT subscription, TSDB, device registry;
|
||||
provides the reading stream to the rules engine.
|
||||
diagram: 0500-building-blocks/ingest.archify
|
||||
tsdb:
|
||||
type: database
|
||||
@@ -20,42 +24,52 @@ elements:
|
||||
sublabel: TimescaleDB
|
||||
brand: postgresql
|
||||
description: >
|
||||
Raw telemetry for 90 days and hourly rollups for 10 years.
|
||||
Responsibility: raw telemetry 90 days, hourly rollups 10 years.
|
||||
Interfaces: provides SQL on 5432 to Device API and dashboard;
|
||||
requires batched writes from Ingest.
|
||||
rules:
|
||||
type: backend
|
||||
label: Rules engine
|
||||
sublabel: alerting
|
||||
description: >
|
||||
Evaluates thresholds and fault codes; raises alerts.
|
||||
Responsibility: evaluates thresholds and fault codes, raises alerts.
|
||||
Interfaces: requires the reading stream from Ingest;
|
||||
provides alerts to the push service and service desk.
|
||||
provisioning:
|
||||
type: security
|
||||
label: Provisioning
|
||||
sublabel: device certs
|
||||
description: >
|
||||
Registers devices and issues their client certificates.
|
||||
Responsibility: registers devices and issues client certificates.
|
||||
Interfaces: provides a REST register call for installers and
|
||||
revocation checks for the broker; requires the device registry.
|
||||
device-registry:
|
||||
type: database
|
||||
label: Device registry
|
||||
sublabel: PostgreSQL
|
||||
brand: postgresql
|
||||
description: >
|
||||
Devices, owners, firmware versions and certificate state.
|
||||
Responsibility: devices, owners, firmware and certificate state.
|
||||
Interfaces: provides SQL on 5432 to Ingest, Provisioning, Device API.
|
||||
device-api:
|
||||
type: backend
|
||||
label: Device API
|
||||
sublabel: REST
|
||||
description: >
|
||||
Serves telemetry and device data to the customer app.
|
||||
Responsibility: serves telemetry and device data to the customer app.
|
||||
Interfaces: provides REST over HTTPS; requires TSDB and device registry.
|
||||
ops-dashboard:
|
||||
type: frontend
|
||||
label: Ops dashboard
|
||||
sublabel: Grafana
|
||||
brand: grafana
|
||||
description: >
|
||||
Fleet view for the operations team, read only on the TSDB.
|
||||
Responsibility: fleet view for the operations team.
|
||||
Interfaces: provides web UI over HTTPS; requires read-only SQL on TSDB.
|
||||
customer-app:
|
||||
type: frontend
|
||||
label: Customer app
|
||||
sublabel: mobile
|
||||
description: >
|
||||
Shows the homeowner their heat pump and its alerts.
|
||||
Responsibility: shows the homeowner their heat pump and alerts.
|
||||
Interfaces: provides the mobile UI; requires Device API and push.
|
||||
Reference in new issue
Block a user