Software-Architektur Blueprint Template

1. Einleitung

Dieses Dokument beschreibt die Architektur des Projekts XYZ, inklusive Systemkontext, Komponenten, Technologien und operativer Aspekte.

Zielgruppe: Entwickler, Architekten, DevOps, Stakeholder Ziel: Verständliche Dokumentation für Design- und Betriebsentscheidungen.

2. Systemübersicht

2.1 Systemkontext (ArchiMate: Business Layer)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
+------------------+        +------------------+
|   Endkunde       |        |   Administrator  |
+------------------+        +------------------+
          |                          |
          v                          v
     +------------------------------------+
     |          Webportal (App)           |
     +------------------------------------+
                |
                v
     +-----------------------------+
     |   Interne Services / API    |
     +-----------------------------+

In ArchiMate:
Business Actor = Endkunde
Application Service = Webportal/API
Business Role = Admin

3. Technologiestack

Komponente	Technologie
Frontend	Vue.js, Bootstrap
Backend	FastAPI (Python)
Authentifizierung	Keycloak, OIDC
Persistenz	PostgreSQL, Redis
Infrastruktur	Kubernetes (kind/dev), Helm
CI/CD	GitLab CI, Skaffold

4. Komponentenarchitektur (ArchiMate: Application Layer)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[ Benutzer-Frontend ]
        |
        v
[ Gateway/API Layer ]
        |
+---------------+----------------+
| Auth Service  | Daten Service  |
+---------------+----------------+
        |               |
        v               v
  [ Keycloak ]     [ PostgreSQL ]

ArchiMate-Elemente:
Application Component = Auth Service, Daten Service
Application Interface = REST API
Application Collaboration = API Layer
Artifact = Helm Chart

5. Datenarchitektur

PostgreSQL: relationale Datenbank
Redis: Cache für Sessions
S3 (Minio): Dateiuploads
Datenmodell: siehe Anhang A (ER-Diagramm)

6. Sicherheitsarchitektur

Auth: OIDC mit Keycloak
Autorisierung: Rollenbasiert + Attribute
TLS: via Caddy mit Auto-HTTPS (Let’s Encrypt)
Secrets: Vault mit Kubernetes Auth

7. Nicht-funktionale Anforderungen

Anforderung	Zielwert
Verfügbarkeit	≥ 99.9% (prod)
Latenz API	≤ 200 ms p95
Skalierbarkeit	horizontal, stateless
Monitoring	Prometheus, Loki, Grafana
Backup	Täglich (DB, S3)

8. Betrieb und Deployment

Environments: dev, staging, prod
Helm-Charts mit Values pro Umgebung
Deployment via Skaffold → Kubernetes
Monitoring & Logging integriert
Deployment-Strategie: Rolling

8. Build & Deployment Pipeline

8.1 Übersicht

Der Build- und Deploymentprozess ist vollständig automatisiert und folgt dem GitOps-Prinzip. Jeder Commit auf den Hauptzweig triggert einen Build, Test und – nach Freigabe – ein Deployment in die Zielumgebung.

Werkzeuge:

Build: Docker, Buildah oder Kaniko
CI/CD: GitLab CI, Skaffold
Deployment: Helm, Kubernetes (Rolling Upgrades)

8.2 Build-Stufen und Quality Gates

Stufe	Inhalte
Linting	Formatierung, statische Analyse (z. B. `ruff`, `eslint`, `golangci-lint`)
Tests	Unit-Tests, Integrationstests, ggf. Snapshot-Tests
Coverage	Mindestabdeckung (z. B. ≥ 80 %), automatischer Report
Security	Dependency-Scan (z. B. `trivy`, `syft`), CVE-Check, Secrets-Scan
Policy	Regeln für Branches, Reviewer, Merge Requests (GitLab Protect Rules)
Image Scan	Signaturprüfung, SBOM, CVE-Scan (`cosign`, `grype`)

Bei Fehler in einem Gate wird der Pipeline-Job abgebrochen. Thresholds sind konfigurierbar.

8.3 Image Inspection & Signierung

Jedes Container-Image wird nach dem Build:

auf Schwachstellen (CVE) überprüft (trivy)
mit einer SBOM versehen (syft)
signiert (cosign)
optional mit notary oder Rekor/OCI attestiert

Images werden nur aus dem internen Container-Registry bereitgestellt und mit Policy Enforcement (z. B. Kyverno/Gatekeeper) auf Cluster-Ebene geprüft.

8.4 Deployment-Strategie

Strategie: Rolling Upgrade via kubectl rollout oder helm upgrade
Readiness-Probes: nötig für zero-downtime Deployments
Rollback: helm rollback / automatischer Fallback bei Deployment-Fehlern
Blue/Green oder Canary: optional über Flagger oder Argo Rollouts

8.5 Lifecycle Management

Phase	Maßnahmen
Pre-Deployment	Migrationen, Secrets, Config, Feature Flags, Pre-Hooks
Deployment	Rolling Upgrade mit Health-Check
Post-Deployment	Smoke-Tests, Canary Check, Metricsprüfung (z. B. Error-Rate)
Decommission	Logs sichern, Metrics archivieren, Stateful Resources entfernen

Optional automatisiert mit Helm hooks oder Skaffold-Lifecycle-Hooks.

8.6 Beispiel: GitLab CI `.gitlab-ci.yml`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
stages:
  - lint
  - test
  - build
  - scan
  - deploy

lint:
  script: ruff check .

test:
  script: pytest --cov

build:
  script: docker build -t registry/app:$CI_COMMIT_SHA .

scan:
  script: trivy image registry/app:$CI_COMMIT_SHA

deploy:
  script: helm upgrade --install myapp ./charts/myapp --set image.tag=$CI_COMMIT_SHA
  environment: production
  only:
    - main

Offene Punkte und Risiken

Noch unklar: Service-Mesh notwendig?
Risiko: Redis Single Point of Failure
Auditlog-Konzept in Arbeit

Anhang

A. ArchiMate Beispiel mit PlantUML (Application View)

@startuml
!define ARCHIMATE https://raw.githubusercontent.com/ebbypeter/PlantUML-Archimate-Icons/master/Archimate
!includeurl ARCHIMATE/ArchimateCommon.puml
!includeurl ARCHIMATE/ApplicationLayer.puml

ApplicationComponent(AppFrontend, "Frontend", "")
ApplicationComponent(AppBackend, "Backend", "")
ApplicationInterface(RestAPI, "REST API", "")

Rel(AppFrontend, RestAPI, "verwendet")
Rel(RestAPI, AppBackend, "reicht weiter")

@enduml

PlantUML Diagramm

Stand: 2025-06-30 Autor: Karsten Krösch Lizenz: CC-BY 4.0

Neurodiverses Office