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,26 @@
schema_version: 1
diagram_type: architecture
meta:
title: Technical context
output: technical-context.html
components:
- ref: engineer
pos: [40, 60]
size: [130, 60]
- ref: wiki-admin
pos: [40, 260]
size: [130, 60]
- ref: wiki
pos: [280, 160]
size: [150, 60]
- ref: idp
pos: [520, 60]
size: [150, 60]
- ref: object-store
pos: [520, 260]
size: [150, 60]
connections:
- { from: engineer, to: wiki, label: HTTPS, variant: emphasis }
- { from: wiki-admin, to: wiki, label: kubectl }
- { from: wiki, to: idp, label: OIDC, variant: security }
- { from: wiki, to: object-store, label: S3 API }
@@ -0,0 +1,47 @@
schema_version: 1
diagram_type: architecture
meta:
title: Building blocks - level 1
output: level-1.html
decisions: [postgres-full-text-search]
components:
- ref: engineer
pos: [40, 160]
size: [130, 60]
- ref: web
pos: [250, 160]
size: [130, 60]
- ref: api
pos: [460, 160]
size: [130, 60]
- ref: db
pos: [460, 360]
size: [130, 60]
- ref: backup-job
pos: [670, 360]
size: [130, 60]
- ref: idp
pos: [670, 60]
size: [130, 60]
- ref: object-store
pos: [880, 160]
size: [130, 60]
boundaries:
- kind: region
label: Team Wiki
wraps: [web, api, db, backup-job]
connections:
- { from: engineer, to: web, label: HTTPS, variant: emphasis }
- { from: web, to: api, label: JSON, variant: emphasis }
- { from: api, to: db, label: SQL, labelAt: [525, 234], decisions: [postgres-full-text-search] }
- { from: api, to: idp, label: OIDC, variant: security }
- { from: api, to: object-store, label: files }
- { from: backup-job, to: db, label: dump }
- { from: backup-job, to: object-store, label: upload }
cards:
- dot: amber
title: 8 Crosscutting concepts
items:
- Access - every request checked against space groups
- Logs - JSON to stdout, collected by the cluster
- Config - environment variables, secrets from the vault
@@ -0,0 +1,55 @@
schema_version: 1
diagram_type: architecture
meta:
title: Building blocks - level 2, Wiki API
output: wiki-api.html
components:
- ref: web
pos: [40, 160]
size: [130, 60]
- id: auth
type: security
label: Auth
sublabel: OIDC session
pos: [250, 60]
size: [130, 60]
- id: pages
type: backend
label: Pages
sublabel: revisions
pos: [250, 160]
size: [130, 60]
- id: search
type: backend
label: Search
sublabel: full-text
pos: [250, 260]
size: [130, 60]
decisions: [postgres-full-text-search]
- id: attachments
type: backend
label: Attachments
pos: [250, 360]
size: [130, 60]
- ref: idp
pos: [460, 60]
size: [130, 60]
- ref: db
pos: [460, 210]
size: [130, 60]
- ref: object-store
pos: [460, 360]
size: [130, 60]
boundaries:
- kind: region
label: Wiki API
wraps: [auth, pages, search, attachments]
connections:
- { from: web, to: auth, label: sign in, variant: security }
- { from: web, to: pages, label: edit, labelAt: [222, 182] }
- { from: web, to: search, label: query }
- { from: web, to: attachments, label: upload }
- { from: auth, to: idp, label: OIDC, variant: security }
- { from: pages, to: db, label: SQL }
- { from: search, to: db, label: SQL }
- { from: attachments, to: object-store, label: S3 }
@@ -0,0 +1,20 @@
schema_version: 1
diagram_type: sequence
meta:
title: Runtime - search and open a page
output: search-page.html
participants:
- ref: engineer
- ref: web
- ref: api
- { ref: db, label: DB }
- { ref: object-store, label: Object store }
messages:
- { from: engineer, to: web, y: 160, label: type query, variant: emphasis }
- { from: web, to: api, y: 210, label: GET /search }
- { from: api, to: db, y: 260, label: full-text query }
- { from: db, to: api, y: 310, label: ranked pages, variant: return }
- { from: api, to: web, y: 360, label: results, variant: return }
- { from: web, to: api, y: 410, label: GET /pages/id }
- { from: api, to: object-store, y: 460, label: signed URL }
- { from: api, to: web, y: 510, label: page, variant: return }
@@ -0,0 +1,19 @@
schema_version: 1
diagram_type: sequence
meta:
title: Runtime - sign in
output: sign-in.html
decisions: [sso-only-via-company-idp]
participants:
- ref: engineer
- ref: web
- ref: api
- { ref: idp, label: Company IdP }
messages:
- { from: engineer, to: web, y: 160, label: open wiki, variant: emphasis }
- { from: web, to: api, y: 210, label: GET /session }
- { from: api, to: web, y: 260, label: redirect, variant: return }
- { from: web, to: idp, y: 310, label: OIDC login, variant: security }
- { from: idp, to: api, y: 360, label: code, variant: return }
- { from: api, to: idp, y: 410, label: token exchange, variant: security }
- { from: api, to: web, y: 460, label: session cookie, variant: return }
@@ -0,0 +1,48 @@
schema_version: 1
diagram_type: architecture
meta:
title: Deployment - production
output: production.html
components:
- ref: engineer
pos: [40, 160]
size: [130, 60]
- id: ingress
type: security
label: Ingress
sublabel: TLS
pos: [250, 160]
size: [130, 60]
- ref: web
pos: [460, 60]
size: [130, 60]
- ref: api
pos: [460, 160]
size: [130, 60]
- ref: db
pos: [670, 160]
size: [130, 60]
- ref: backup-job
pos: [670, 360]
size: [130, 60]
- ref: idp
pos: [460, 460]
size: [130, 60]
- ref: object-store
pos: [880, 460]
size: [130, 60]
boundaries:
- kind: region
label: Company cluster
wraps: [ingress, web, api, db, backup-job]
- kind: security-group
label: Namespace team-wiki
wraps: [web, api, db, backup-job]
connections:
- { from: engineer, to: ingress, label: HTTPS, variant: emphasis }
- { from: ingress, to: web, label: static }
- { from: ingress, to: api, label: /api, variant: emphasis }
- { from: api, to: db, label: SQL }
- { from: api, to: idp, label: OIDC, variant: security, labelAt: [525, 234] }
- { from: backup-job, to: db, label: dump }
- { from: backup-job, to: object-store, label: S3 }
@@ -0,0 +1,20 @@
schema_version: 1
decision:
id: postgres-full-text-search
title: PostgreSQL full-text search, no search engine
status: accepted
date: 2026-10-05
elements: [api, db]
diagrams: [0500-building-blocks/level-1.archify, 0500-building-blocks/wiki-api.archify]
context: >
The wiki holds a few thousand pages for one team. A
separate search engine would be one more service to run,
back up and keep in sync.
decision: >
Search uses PostgreSQL full-text search on a generated
column of each page. The API queries it in the same
transaction as the page data.
consequences: >
Results are never stale and backups cover search too.
Ranking is simpler than a search engine. Revisit when
the wiki grows past 100000 pages.
@@ -0,0 +1,19 @@
schema_version: 1
decision:
id: sso-only-via-company-idp
title: Sign-in only through the company identity provider
status: accepted
date: 2026-10-12
elements: [idp, api, web]
diagrams: [0300-context/technical-context.archify, 0600-runtime/sign-in.archify]
context: >
Leavers kept access to the old wiki because it had its
own passwords. Nobody owned the user list.
decision: >
The wiki has no local accounts. Users sign in with OIDC
at the company identity provider; team groups map to
wiki spaces.
consequences: >
Offboarding removes wiki access at once. The wiki cannot
be used when the identity provider is down. The admin
needs a break-glass account kept in the vault.
@@ -0,0 +1,66 @@
schema_version: 1
model:
id: team-wiki
name: Team Wiki
description: >
An arc42 example: a small self-hosted wiki for an engineering
team. Sections 1 goals, 2 constraints, 3 business context,
10 quality, 11 risks and 12 glossary are on this overview;
0300-context holds 3 technical context, 0500-building-blocks
5 building blocks, 0600-runtime 6 runtime, 0700-deployment
7 deployment and decisions 9 architecture decisions.
diagram_type: architecture
meta:
title: Team Wiki - business context
output: main.html
decisions: [sso-only-via-company-idp]
components:
- ref: engineer
pos: [40, 60]
size: [130, 60]
- ref: wiki-admin
pos: [40, 260]
size: [130, 60]
- ref: wiki
pos: [280, 160]
size: [150, 60]
- ref: idp
pos: [520, 60]
size: [150, 60]
- ref: object-store
pos: [520, 260]
size: [150, 60]
connections:
- { from: engineer, to: wiki, label: reads, variant: emphasis }
- { from: wiki-admin, to: wiki, label: runs }
- { from: wiki, to: idp, label: sign-in, variant: security }
- { from: wiki, to: object-store, label: files }
cards:
- dot: cyan
title: 1 Quality goals
items:
- Findability - any page found in two searches
- Security - only current staff can read
- Operability - one person runs it in an hour a week
- dot: slate
title: 2 Constraints
items:
- Runs on the company Kubernetes cluster
- Sign-in only via the company identity provider
- dot: emerald
title: 10 Quality scenarios
items:
- A search over 5000 pages answers in under 1 s
- A leaver loses access within 5 minutes
- The admin restores last night's state in 30 minutes
- dot: rose
title: 11 Risks
items:
- Identity provider outage blocks all sign-ins
- Backups untested until a restore drill is run
- dot: violet
title: 12 Glossary
items:
- Space - pages of one team, mapped to a group
- Revision - one saved version of a page
- Attachment - a file stored beside a page
@@ -0,0 +1,33 @@
schema_version: 1
elements:
web:
type: frontend
label: Web App
sublabel: React
brand: react
description: >
Page editor, viewer and search box in the browser; talks
only to the API.
api:
type: backend
label: Wiki API
sublabel: REST
description: >
Pages, search, attachments and access checks; the only
writer of the database.
diagram: 0500-building-blocks/wiki-api.archify
db:
type: database
label: Database
sublabel: PostgreSQL
brand: postgresql
description: >
Pages, revisions, users and the full-text index; the
source of truth.
backup-job:
type: backend
label: Backup job
sublabel: nightly
description: >
Dumps the database at 02:00 and writes it to the backup
bucket; keeps 30 days.
@@ -0,0 +1,15 @@
schema_version: 1
elements:
engineer:
type: external
label: Engineer
sublabel: team member
description: >
Reads and edits pages, searches, attaches files; signs in
with the company account.
wiki-admin:
type: external
label: Wiki admin
sublabel: platform team
description: >
Runs the wiki, restores backups and manages spaces.
@@ -0,0 +1,24 @@
schema_version: 1
elements:
wiki:
type: cloud
label: Team Wiki
sublabel: the system
description: >
Everything we build and run; web app, API, database and
the backup job.
diagram: 0500-building-blocks/level-1.archify
idp:
type: security
label: Identity provider
sublabel: company SSO
description: >
The company identity provider; signs users in over OIDC
and owns team membership.
object-store:
type: external
label: Object storage
sublabel: S3-compatible
description: >
Company object storage; holds attachments and nightly
backups in separate buckets.