8. Cross-cutting Concepts¶

Help: This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (i.e., cross-cutting) of your system. Such concepts are often related to multiple building blocks. They can include many different topics, such as:

Domain model

Architecture and design patterns

Rules for using specific technology

Principal, often technical decisions of overall decisions

Implementation rules

Motivation: Concepts form the basis for conceptual integrity (consistency, homogeneity) of the architecture. Thus, they are an important contribution to achieving inner qualities of your system. Some of these concepts cannot be assigned to individual building blocks (e.g., security or safety). This is the place in the template to describe concepts that span multiple parts of the system.

Form: The form can be varied: - Concept papers with any kind of structure - Cross-cutting model excerpts or scenarios using the notations of the other architecture views - Sample implementations, especially for technical concepts - Reference to typical usage of standard frameworks (e.g., using Hibernate for object/relational mapping)

8.1 Domain Model¶

Help: Describe the core domain model or entity model that is shared across the system. This is especially important in domain-driven design approaches.

\<Insert a domain model diagram showing key entities and their relationships.>

Key Domain Entities¶

Entity	Description	Bounded Context
\<Entity A>	\<Description of this entity and its role in the domain>	\<Context name>
\<Entity B>	\<Description of this entity and its role in the domain>	\<Context name>
\<Entity C>	\<Description of this entity and its role in the domain>	\<Context name>

8.2 Persistence¶

Help: Describe the approach to data persistence, including database choices, ORM strategies, data migration approach, and data lifecycle management.

Aspect	Approach	Details
\<Primary Storage>	\<e.g., PostgreSQL with JPA/Hibernate>	\<ACID transactions, connection pooling>
\<Caching>	\<e.g., Redis>	\<TTL-based expiration, cache-aside pattern>
\<Search Index>	\<e.g., Elasticsearch>	\<Full-text search, analytics>
\<File Storage>	\<e.g., S3-compatible object store>	\<Documents, media, backups>
\<Schema Migration>	\<e.g., Flyway / Liquibase>	\<Version-controlled, forward-only>

8.3 User Interface¶

Help: Describe common UI concepts, design systems, and frontend architecture patterns that apply across the system.

Aspect	Approach
\<Design System>	\<e.g., Material Design with custom theme>
\<Frontend Framework>	\<e.g., React with TypeScript>
\<State Management>	\<e.g., Redux Toolkit / Zustand>
\<Accessibility>	\<WCAG 2.1 AA compliance>
\<Internationalization>	\<i18next with lazy-loaded bundles>
\<Responsive Design>	\<Mobile-first, breakpoints at 768px/1024px/1440px>

8.4 Security¶

Help: Describe the security concepts applied across the system, including authentication, authorization, data protection, and security patterns.

Aspect	Approach	Details
\<Authentication>	\<e.g., OAuth 2.0 + OIDC>	\<Identity provider, token format, session management>
\<Authorization>	\<e.g., RBAC with policy engine>	\<Role hierarchy, permission model>
\<Transport Security>	\<TLS 1.3 everywhere>	\<Certificate management, mutual TLS for services>
\<Data Protection>	\<Encryption at rest and in transit>	\<AES-256, KMS-managed keys>
\<Input Validation>	\<Server-side validation mandatory>	\<Schema validation, sanitization>
\<Secrets Management>	\<e.g., HashiCorp Vault>	\<Dynamic secrets, automatic rotation>
\<Audit Logging>	\<Immutable audit trail>	\<Who did what, when, from where>

8.5 Error Handling and Logging¶

Help: Describe the cross-cutting approach to error handling, logging, and observability.

Error Handling Strategy¶

Error Type	Handling Approach
\<Validation errors>	\<Return 400 with structured error response>
\<Business rule violations>	\<Return 422 with domain-specific error codes>
\<Downstream failures>	\<Circuit breaker, fallback, retry with backoff>
\<Unexpected errors>	\<Return 500, log details, alert operations>

Logging Standard¶

Aspect	Standard
\<Format>	\<Structured JSON>
\<Correlation>	\<X-Correlation-ID header propagated across services>
\<Levels>	\<ERROR, WARN, INFO, DEBUG (configurable per service)>
\<Sensitive Data>	\<PII must be masked or excluded from logs>
\<Retention>	\<30 days hot, 1 year cold storage>

8.6 Communication and Integration¶

Help: Describe patterns for inter-service communication and external integrations.

Pattern	Use Case	Technology
\<Synchronous REST>	\<Query operations, CRUD>	\<HTTP/2, JSON, OpenAPI spec>
\<Asynchronous Messaging>	\<Event notifications, decoupled processing>	\<Kafka / RabbitMQ>
\<gRPC>	\<High-performance internal communication>	\<Protocol Buffers, HTTP/2>
\<WebSocket>	\<Real-time updates to clients>	\<Socket.IO / native WebSocket>

8.7 Testability¶

Help: Describe the testing strategy and patterns used across the system.

Test Level	Scope	Tools	Responsibility
\<Unit Tests>	\<Individual functions/classes>	\<JUnit / Jest / pytest>	\<Developer>
\<Integration Tests>	\<Service + dependencies>	\<Testcontainers>	\<Developer>
\<Contract Tests>	\<API compatibility>	\<Pact>	\<Both consumer & provider teams>
\<E2E Tests>	\<Full user journeys>	\<Cypress / Playwright>	\<QA team>
\<Performance Tests>	\<Load and stress testing>	\<k6 / Gatling>	\<Performance team>

8.8 Monitoring and Observability¶

Help: Describe the observability strategy including metrics, tracing, and alerting.

Pillar	Tool	Purpose
\<Metrics>	\<Prometheus + Grafana>	\<System and business metrics dashboards>
\<Distributed Tracing>	\<Jaeger / OpenTelemetry>	\<Request flow across services>
\<Log Aggregation>	\<ELK Stack / Loki>	\<Centralized log search and analysis>
\<Alerting>	\<PagerDuty / OpsGenie>	\<Incident notification and escalation>
\<Health Checks>	\<K8s liveness/readiness probes>	\<Automated failure detection>

Based on the arc42 architecture template (https://arc42.org).
Created by Dr. Peter Hruschka and Dr. Gernot Starke.
Licensed under CC BY-SA 4.0.