Diat für Architekturdokumentation: Ein Ernährungsplan

Transcript

1. Ein Ernährungsplan Diät für Eure Architektur- dokumentation Dr. Gernot Starke Fellow
2. TL;DR arc42 erlaubt strukturierte, zielgerichtete Kommunikation über Software-/IT-Architekturen. Schmerzfreie Dokumentation.
3. Dr. Gernot Starke INNOQ Fellow üArchitekturverbesserer üCoach, Trainer üINNOQ-Fellow üarc42, aim42 üiSAQB
4. Architektur ἀρχιτεκτονική (architektonikḗ) = Baukunst
5. Architektur: Zwei Arten von Entscheidungen! 1.) Struktur- entscheidungen (aka: Grundriss)
6. Zwei Arten von Entscheidungen! 2.) Baumaterial 1.) Struktur (Grundriss)
7. Was musst Du beim Programmieren entscheiden? 2.) Technik und Methoden 1.) Struktur
8. Diät von altgriechisch δίαιτα, ursprünglich „Lebensweise“
9. Diät
10. Lebensweise
12. Informationen zu Architektur eines IT-Systems
13. metaphorisch J So sieht’s aus
14. https://www.einrichten-24.com/products/116263we-116263as-116263hg
15. 12 nützliche Fächer für alle relevanten Informationen rund um Ihr IT-System
16. Schrank für Softwarearchitektur Anforderungen Entscheidungen Strukturen von Quellcode Technologie, Methoden, Konzepte externe Schnittstellen https://www.einrichten-24.com/products/116263we-116263as-116263hg
17. arc42, Version 9.1, Stand Dezember 2025. © Dr. Peter Hruschka und Dr. Gernot Starke. Frei für kommerzielle und private Nutzung.
18. und Architektur
19. Zwei Arten von Entscheidungen! 2.) Baumaterial 1.) Struktur (Grundriss) W iederholung
20. arc42 und Architektur... Struktur Material
21. Grund- regel
22. glutenfrei vegan veggie ohne Tomaten
23. Anforderungen an Doku VOR der Umsetzung (der Diät) klären. (selbstverständlich)
24. Wer braucht was?
25. 1. Introduction & Goals 6. Runtime View 8. Crosscutting 10. Quality Requirements 4. Solution Strategy 12. Glossary 7. Deployment View 5. Building Block View 3. Context & Scope 2. Constraints 9. Architectural Decisions 11. Risks & Technical Debt Cross-cutting topics, often very technical and detailed Hardware, infrastructure & deployment important and specific terms („ubiquitous language“) fundamental requirements, top quality goals External systems & interfaces important runtime scenarios Core ideas and solution approaches Structure of source code, modularisation (hierarchical) Overview plus quality scenarios Important decisions (not described elsewhere) Known problems and risks Concepts Anforderungen an Doku Beachte ebenfalls: • Requirements documentation • Test documentation • Operations documentation • User documentation • <you-name-it> Stakeholder Needed Documentation Reason
26. So sieht’s aus
27. Beispiel (Datenmigration, 4000+ PT) Sparsam! 17 Seiten 7 Diagramme
28. Beispiel (“CRM“, 2000+ PT) 43 Seiten (davon 8 Formalia) 9 Diagramme 18 Tabellen
29. arc42 in sparsam
30. arc42 – am Beispiel
32. 1: Fundamental Requirements Title Requirement Publish usage statistics publish current usage statistics of arc42 websites Publish repo statistics publish current repository statistics (like issues, bugs) of arc42 websites Persistent results store important results and events persistently for future reference Current updates inform owners of important system events, like „somebody has requested the statistics“ or „server restarted“
33. 1.2: Quality Requirements Property Q-Req-ID Quality Requirement / Q-Scenario Accurate Q-1 Site usage (like pageviews, visitor counts) results have to be correct. Spam- and bot traffic shall be excluded from counts. Error rates in data representation should be below 0.5% as measured by data quality checks. Environment friendly Q-2 Reduce computing resources as much as possible: Complete data reload must have < 10 API requests per displayed website. Available Q-3 Available: statics are available via the website 24x7. Short periods (hours) of downtime (max 8h) can be allowed, in such cases cached or dated results shall be displayed Simple, understandable visualization Q-4 Data has to be displayed in easily understandable manner, e.g. numerical tables. At least 90% of users should be able to understand the displayed data without further instruction, as measured by a user survey. Reliable Q-5 Uptime of 99.9% per month. Error rates (including server errors, and data access issues) should not exceed 0.1% of all system transactions. Secure Q-6 Compliant with EU data privacy regulations, no cookies, no tracking over multiple sites, „privacy friendly“.
34. 3: Context Element Explanation Plausible.io Maintains precise statistics of site access Fly.io (cloud) host for backend Turso DB (cloud-based) distributed database for results Slack Messaging tool to send updates to subscribers GitHub Gives access to current issue/bug counts of site repositories
35. 4: Solution Strategy: Mono-Repo
36. 4: Solution Strategy Strategy Requirement Explanation Caching of results Environment-friendly save remote requests / network traffic by caching results for (configurable) amount of time External data provider Accurate, secure Delegate usage counter to external service (plausible.io), which handles GDPR compliance Cloud hosted in multiple regions Reliable, available use established Hyperscaler (fly.io) and distributed database (turso.tech) for 99.99% availability and low latency Backend in Go Well-suited for cloud operations, drivers for all external APIs available for Go. Attractive for developers.
37. 5: Building Blocks – Level 1 Element Explanation api- gateway receives API requests and dispatches to domain main application startup and initialization domain „business logic“, mainly coordination of external systems types specific data types and – structures ≪wrapper≫ wrapping details of external systems, responsible for access
38. 6: Runtime View – CORS
39. 7: Concept: Handling API Secrets
40. Architecture Decisions
42. 1. Introduction & Goals 6. Runtime View 8. Crosscutting 10. Quality Requirements 4. Solution Strategy 12. Glossary 7. Deployment View 5. Building Block View 3. Context & Scope 2. Constraints 9. Architectural Decisions 11. Risks & Technical Debt Cross-cutting topics, often very technical and detailed Hardware, infrastructure & deployment important and specific terms („ubiquitous language“) fundamental requirements, top quality goals External systems & interfaces important runtime scenarios Core ideas and solution approaches Structure of source code, modularisation (hierarchical) Overview plus quality scenarios Important decisions (not described elsewhere) Known problems and risks Concepts
43. Menschen “abholen”
44. grob, Überblick detailliert Reihenfolge beim Erklären
50. Beliebige Reihenfolge beim Arbeiten
51. Aller Anfang...
53. Aller Anfang... ist klein und kompakt
54. ERD Block Petri
55. ERD Block Petri ... A canvas is a structured visualization that facilitates understanding and analysis of key elements of specific topics.. Canvas
56. arc42 Canvas
57. ERD Block Petri https://canvas.arc42.org
59. Health-Insurance Card ERD Block Petri
60. kleine Systeme ?
61. Microservice -Doku
62. Microservice -Doku
63. Juni 2024 zeige „Evolution“… Dezember 2024 Juni 2025
64. Tooling (1) draw.io, diagrams.net
65. Tooling (2) pptx
66. Tooling (3) Miro
67. große Systeme ?
68. Große Systeme Zerlege Doku in „Module“
69. Macro Architecture Macro Architecture 11. Risk & Technical Debt Subsystem #1 1. Introduction and goals 2. Constraints 3. Context 5. Building Block View 6. Runtime View 7. Deployment View 8. Crosscutting Concepts 10. Quality Requirements 9. Architecture Decisions 4. Solution Strategy 12. Glossary Subsystem #2 Subsystem #3 8. Concepts 9. Architecture Decisions 4. Solution Strategy approaches, decisions, patterns, practices, principiles, products, rules, technologies that hold for „nearly everything“ reference reference reference reference or example implementations, appropriate documentation „overall picture“
70. wenn Du Hilfe brauchst
71. zuerst: https://docs.arc42.org
72. https://docs.arc42.org
73. arc42: Ökosystem
74. Beispiele anschauen
75. 380 9 Seiten real-world Beispiele
76. Zukunft alle LLMs kennen arc42 (und den arc42-Canvas, ADRs, mermaid/plantuml..).
77. Ausblick...
78. Ausblick...
79. Danke. Gernot Starke gernot.starke@innoq.com LinkedIn: gernotstarke