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

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

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

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

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)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

@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

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