At the beginning everything is clear:

This has a heavy price in the long run

Source code is a low-level abstraction — it does not contain:

• ✗ Overall large-scale structure
• ✗ Architectural decisions
• ✗ Rationale for those decisions
• ✗ Technology choices
• ✗ Description of cross-cutting concerns
• ✗ Cannot be read by all stakeholders (project managers / product managers, designers, analysts, etc.)

• → Architecture documents, diagrams, and models
• → Summarized, curated, and version-controlled
• → Designed for long-term reference and reuse
• → Reaches stakeholders asynchronously
• → Slower to produce — but persistent and precise

• → Explain, present, and discuss architecture
• → Gather quick feedback from stakeholders
• → Drive decisions in real time
• → Build mutual understanding across teams
• → Fast, bi-directional, and context-rich

Judged only by readers. Tailor form, content, and level of detail to the stakeholder audience.

Right information for intended stakeholders. Addresses their needs and helps them perform their job.

Content must be accurate and up-to-date at all times.

Strive for brevity and conciseness. Reflected in structure, organization, language, and content.

Easy to keep updated as the system evolves.

• →Building blocks
• →Interaction of building blocks
• →Source code structure
• →Technical infrastructure
• →Basic assumptions, decisions, technologies & concepts

• +Often easier to understand
• +Appeals to visual memory

• −High effort to create and maintain
• −Might be misleading if not explained properly

Components, interfaces & dependencies — used for building block views.

Nodes, artifacts & infrastructure — shows where components run.

Classes, attributes, methods & relationships — domain models & key interfaces.

Code organized into packages/modules — layered or modular architecture.

Object interactions over time — best for runtime views & request/response flows.

Workflow & process flow — supports parallel flows (fork/join).

System features from user perspective — actors + use cases + associations.

Lifecycle of an object — states, transitions & events (order lifecycle example).

• → System as a black box in its environment
• → Defines external actors, systems & interfaces
• → Establishes the system boundary
• → Typically the first view to create
• Audience: all stakeholders · UML: Component diagram

• → Static decomposition into hierarchical levels
• → Each block: black box with white box refinements
• → Backbone of architecture documentation
• → Level 1 → Level 2 → Level 3 …
• Audience: developers, architects · UML: Component

• → Dynamic behavior for key scenarios
• → How components interact at runtime
• → Reveals concurrency, timing & failure modes
• → Message flows, request-response sequences
• Audience: devs, testers · UML: Sequence diagram

• → Infrastructure & where software runs
• → Nodes, network topology & artifacts
• → Scaling, redundancy & distribution
• → Cloud deployments, microservices infrastructure
• Audience: operations, DevOps · UML: Deployment

Provide additional views according to stakeholder needs.

• →High-level architecture for communication to management
• →Data view
• →Security view

• ⚠Views are interdependent
• ⚠Changes to one view can have an impact on other views, either positive or negative
• ⚠Ensure architecture views are updated in each iteration of an iterative approach
• ✓The four presented view types are usually sufficient

The persistence layer is responsible for managing the storage, retrieval, and update of data throughout the software application. Key requirements include:

• →Data Access: Efficient and secure access to stored data.
• →Data Integrity: Ensure data is accurately stored and retrieved without corruption.
• →Abstraction from Database: The solution should abstract away the implementation of the storage technology from the application code.
• …

• →Technology Compatibility: The solution must integrate seamlessly with the existing technology stack. (Java, PostgreSQL)
• →Open Source and Community Support.

ORM (Object-Relational Mapping) with JPA: Use Hibernate ORM for mapping application domain objects to the relational database tables.

try {
    session.beginTransaction();
    Long studentId = 2L;
    Student student = session.get(Student.class, studentId);
    if (student != null) {
        System.out.println("Found: " + student.getName());
    } else {
        System.out.println("No student found with ID " + student.getId());
    }
    session.getTransaction().commit();
} finally {
    session.close();
    sessionFactory.close();
}

• ⚠Performance Overhead: ORM can introduce overhead, particularly with complex queries or large datasets, impacting performance.
• ⚠Complexity in Transaction Management: Managing transactions can become complex, especially in distributed systems.
• …

• ✗JDBC Direct Usage: Considered for its performance and control over SQL execution but rejected due to higher development effort and potential for SQL injection vulnerabilities.
• …

• → Well-designed and documented internal and external interfaces are the backbone of a maintainable architecture.
• ⚠ Specification of external interfaces can require a lot of effort.

• →Plan for API evolution and versioning if necessary
• →Use tools (e.g., Swagger) or API description languages when appropriate
• →Test cases can be a resource for interface documentation
• →Some stakeholders may require a stand-alone interface documentation
• →Provide templates for interface documentation with a common structure

Use standardized structures and templates:

• →Uniform documentation with consistent structure
• →Increases efficiency to create and use
• →What is missing? What do I have to document? Where?
• →Quality assurance: all aspects to be covered are defined in advance

⚠ Ensure compliance with the structure!

💡 Less is more! Time investment on concise writing saves readers valuable time.

• →Write thoughts and ideas in a logical or required sequence
• →Use active voice: ✓ "The application verifies the user input" · ✗ "The user input is verified by the application"
• →KISS: Avoid unnecessary technical jargon
• →Explain technical terms

• →Avoid unnecessary repetition!
• →Simplifies the use of documentation
• →Increases efficiency
• →Reduces effort for maintenance and changes

Ambiguity can lead to inefficient conversations due to different interpretations.

• →Use formal description languages if applicable
• →Use self-descriptive names for domain objects
• →Link to a glossary for an explanation of terms
• →Verify if things can be misunderstood

Helps readers understand the architecture decisions and their implications.

• →A decision includes the reasoning that led to that decision
• →Advantages/disadvantages of decisions are usually not obvious

Provide a written justification of important decisions to:

• →Traceability back to requirements and constraints increases understanding
• →Eliminate endlessly repetitive discussions
• →Save time when decisions need to be reconsidered when conditions change

"Illustrations should not impress but enlighten."

• →Avoid too large or too complex diagrams
• →Consider the 7 ± 2 rule — 5–9 elements in diagrams are an optimum for understandability
• →Exception: "architectural wallpaper"

Regularly update documentation during development and maintenance!

Lack of a consistently used maintenance process for documentation leads to:

• ✗Inconsistent and outdated documentation
• ✗Reduced benefit and usage of documentation
• ✗Unnecessary inquiries from other stakeholders (especially architects or developers)
• ✗Decreased motivation for creating and maintaining documentation

Documentation evolves! — How current/outdated is the given information?

• →Establish version control for documentation as well
• →How stable is it? Are changes to be expected?

Perform reviews before publishing!

• →Only the target user group can decide whether the right information is presented in the right way
• →Let representatives of the target group participate in the documentation process
• →New team members are a valuable source for feedback