arc42 and ArchiMate layouts in the folder guide; arc42 examples cover all sections; 1.3
references/folders.md gains arc42 (sections as numbered folders and cards, black boxes, quality tree) and ArchiMate (layers, type in tag and sublabel, element mapping). Gotchas: ref in every kind needs extension 0.11.0; tags are not drawn on the box.
This commit is contained in:
1 parent
d9777fb90e
commit
900e0986e6
20 files changed
+554
-89
No files matched your search
@@ -24,3 +24,11 @@ connections:
|
||||
- { from: wiki-admin, to: wiki, label: kubectl }
|
||||
- { from: wiki, to: idp, label: OIDC, variant: security }
|
||||
- { from: wiki, to: object-store, label: S3 API }
|
||||
cards:
|
||||
- dot: cyan
|
||||
title: 3 Domain interfaces
|
||||
items:
|
||||
- "Engineer: in edits, queries, files; out pages, results"
|
||||
- "Wiki admin: in deploys, restore commands; out status, logs"
|
||||
- "Identity provider: out sign-in code, groups; in token requests"
|
||||
- "Object storage: out attachments, backups; in signed URL reads"
|
||||
@@ -42,6 +42,9 @@ 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
|
||||
- "Security: OIDC session, every request checked against space groups"
|
||||
- "Persistence: PostgreSQL is the only source of truth"
|
||||
- "Errors: API returns problem JSON; the web app shows a retry"
|
||||
- "Logging: JSON to stdout, collected by the cluster"
|
||||
- "Backups: nightly dump to object storage, 30 days"
|
||||
- "Config: environment variables, secrets from the vault"
|
||||
@@ -36,8 +36,11 @@ boundaries:
|
||||
label: Company cluster
|
||||
wraps: [ingress, web, api, db, backup-job]
|
||||
- kind: security-group
|
||||
label: Namespace team-wiki
|
||||
wraps: [web, api, db, backup-job]
|
||||
label: App node pool
|
||||
wraps: [web, api]
|
||||
- kind: security-group
|
||||
label: Data node
|
||||
wraps: [db, backup-job]
|
||||
connections:
|
||||
- { from: engineer, to: ingress, label: HTTPS, variant: emphasis }
|
||||
- { from: ingress, to: web, label: static }
|
||||
@@ -46,3 +49,12 @@ connections:
|
||||
- { 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 }
|
||||
cards:
|
||||
- dot: slate
|
||||
title: 7 Mapping
|
||||
items:
|
||||
- "Web App -> app node pool, nginx pod, namespace team-wiki"
|
||||
- "Wiki API -> app node pool, 2 pods behind the ingress"
|
||||
- "Database -> data node, PostgreSQL stateful set with volume"
|
||||
- "Backup job -> data node, Kubernetes CronJob"
|
||||
- "Attachments, backups -> company object storage buckets"
|
||||
@@ -0,0 +1,77 @@
|
||||
schema_version: 1
|
||||
diagram_type: architecture
|
||||
meta:
|
||||
title: Quality tree
|
||||
output: quality-tree.html
|
||||
legend:
|
||||
mode: hidden
|
||||
components:
|
||||
- id: quality
|
||||
type: cloud
|
||||
label: Quality
|
||||
pos: [40, 200]
|
||||
size: [130, 120]
|
||||
- id: usability
|
||||
type: frontend
|
||||
label: Usability
|
||||
pos: [250, 60]
|
||||
size: [130, 60]
|
||||
- id: security
|
||||
type: security
|
||||
label: Security
|
||||
pos: [250, 160]
|
||||
size: [130, 60]
|
||||
- id: reliability
|
||||
type: backend
|
||||
label: Reliability
|
||||
pos: [250, 310]
|
||||
size: [130, 60]
|
||||
- id: maintainability
|
||||
type: backend
|
||||
label: Maintainability
|
||||
pos: [250, 460]
|
||||
size: [130, 60]
|
||||
- id: q-search
|
||||
type: external
|
||||
label: Search under 1 s
|
||||
pos: [460, 60]
|
||||
size: [170, 60]
|
||||
- id: q-leaver
|
||||
type: external
|
||||
label: Leaver out in 5 min
|
||||
pos: [460, 160]
|
||||
size: [170, 60]
|
||||
- id: q-restore
|
||||
type: external
|
||||
label: Restore in 30 min
|
||||
pos: [460, 260]
|
||||
size: [170, 60]
|
||||
- id: q-pod
|
||||
type: external
|
||||
label: Pod back in 1 min
|
||||
pos: [460, 360]
|
||||
size: [170, 60]
|
||||
- id: q-upgrade
|
||||
type: external
|
||||
label: Upgrade in 1 hour
|
||||
pos: [460, 460]
|
||||
size: [170, 60]
|
||||
connections:
|
||||
- { from: quality, to: usability }
|
||||
- { from: quality, to: security }
|
||||
- { from: quality, to: reliability }
|
||||
- { from: quality, to: maintainability }
|
||||
- { from: usability, to: q-search }
|
||||
- { from: security, to: q-leaver }
|
||||
- { from: reliability, to: q-restore }
|
||||
- { from: reliability, to: q-pod }
|
||||
- { from: maintainability, to: q-upgrade }
|
||||
cards:
|
||||
- dot: emerald
|
||||
title: 10 Quality scenarios
|
||||
items:
|
||||
- "Search: an engineer searches 5000 pages; results in under 1 s"
|
||||
- "Leaver: HR disables an account; wiki access ends within 5 minutes"
|
||||
- "Restore: the database is lost; the admin restores last night in 30 minutes"
|
||||
- "Crash: an API pod dies; the cluster restarts it, no data lost, back in 1 minute"
|
||||
- "Upgrade: a new wiki version ships; one admin rolls it out in 1 hour"
|
||||
@@ -3,12 +3,14 @@ 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.
|
||||
An arc42 example: a small self-hosted wiki for an engineering team.
|
||||
1 Requirements, quality goals, stakeholders; 2 Constraints;
|
||||
4 Solution strategy; 11 Risks; 12 Glossary: cards on this overview.
|
||||
3 Context: this overview (business) and 0300-context (technical).
|
||||
5 Building blocks: 0500-building-blocks, black boxes in registry/.
|
||||
6 Runtime: 0600-runtime. 7 Deployment: 0700-deployment.
|
||||
8 Crosscutting concepts: card on 0500-building-blocks/level-1.
|
||||
9 Decisions: decisions/. 10 Quality: 1000-quality.
|
||||
diagram_type: architecture
|
||||
meta:
|
||||
title: Team Wiki - business context
|
||||
@@ -36,31 +38,48 @@ connections:
|
||||
- { from: wiki, to: idp, label: sign-in, variant: security }
|
||||
- { from: wiki, to: object-store, label: files }
|
||||
cards:
|
||||
- dot: cyan
|
||||
title: 1 Quality goals
|
||||
- dot: orange
|
||||
title: 1.1 Requirements
|
||||
items:
|
||||
- Findability - any page found in two searches
|
||||
- Security - only current staff can read
|
||||
- Operability - one person runs it in an hour a week
|
||||
- "Create, edit and version pages in team spaces"
|
||||
- "Full-text search over every page a user may read"
|
||||
- "Attach files to pages"
|
||||
- "Admin restores the wiki from a nightly backup"
|
||||
- dot: cyan
|
||||
title: 1.2 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: amber
|
||||
title: 1.3 Stakeholders
|
||||
items:
|
||||
- "Engineer: fast search, simple editor"
|
||||
- "Wiki admin: little routine work, easy restore"
|
||||
- "Security officer: no access after leaving"
|
||||
- "Team lead: one place for team knowledge"
|
||||
- dot: slate
|
||||
title: 2 Constraints
|
||||
items:
|
||||
- Runs on the company Kubernetes cluster
|
||||
- Sign-in only via the company identity provider
|
||||
- "Runs on the company Kubernetes cluster"
|
||||
- "Sign-in only via the company identity provider"
|
||||
- dot: emerald
|
||||
title: 10 Quality scenarios
|
||||
title: 4 Solution strategy
|
||||
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
|
||||
- "React, Node.js API, PostgreSQL: one stack the team knows"
|
||||
- "Three blocks plus a backup job: operability"
|
||||
- "Findability: PostgreSQL full-text search (postgres-full-text-search)"
|
||||
- "Security: OIDC at the company IdP only (sso-only-via-company-idp)"
|
||||
- "Operability: files and backups in company object storage"
|
||||
- dot: rose
|
||||
title: 11 Risks
|
||||
title: 11 Risks and technical debt
|
||||
items:
|
||||
- Identity provider outage blocks all sign-ins
|
||||
- Backups untested until a restore drill is run
|
||||
- "Risk: identity provider outage blocks all sign-ins"
|
||||
- "Risk: backups untested until a restore drill is run"
|
||||
- "Debt: attachments are not virus-scanned yet"
|
||||
- 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
|
||||
- "Space: pages of one team, mapped to a group"
|
||||
- "Revision: one saved version of a page"
|
||||
- "Attachment: a file stored beside a page"
|
||||
@@ -6,15 +6,17 @@ elements:
|
||||
sublabel: React
|
||||
brand: react
|
||||
description: >
|
||||
Page editor, viewer and search box in the browser; talks
|
||||
only to the API.
|
||||
Responsibility: page editor, viewer and search box in the
|
||||
browser. Interfaces: provides the UI over HTTPS; requires
|
||||
the Wiki API (JSON).
|
||||
api:
|
||||
type: backend
|
||||
label: Wiki API
|
||||
sublabel: REST
|
||||
description: >
|
||||
Pages, search, attachments and access checks; the only
|
||||
writer of the database.
|
||||
Responsibility: pages, search, attachments and access checks;
|
||||
the only writer of the database. Interfaces: provides REST
|
||||
JSON; requires the IdP (OIDC), the database (SQL), object storage (S3).
|
||||
diagram: 0500-building-blocks/wiki-api.archify
|
||||
db:
|
||||
type: database
|
||||
@@ -22,12 +24,14 @@ elements:
|
||||
sublabel: PostgreSQL
|
||||
brand: postgresql
|
||||
description: >
|
||||
Pages, revisions, users and the full-text index; the
|
||||
source of truth.
|
||||
Responsibility: pages, revisions, users and the full-text
|
||||
index; the source of truth. Interfaces: provides SQL to the
|
||||
API and dumps to the backup job.
|
||||
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.
|
||||
Responsibility: dumps the database at 02:00, keeps 30 days.
|
||||
Interfaces: requires the database (pg_dump) and the backup
|
||||
bucket (S3); provides none.
|
||||
Reference in new issue
Block a user