0%

Book Description

Document the architecture of your software easily with this highly practical, open-source template.

Key Features

  • Get to grips with leveraging the features of arc42 to create insightful documents
  • Learn the concepts of software architecture documentation through real-world examples
  • Discover techniques to create compact, helpful, and easy-to-read documentation

Book Description

When developers document the architecture of their systems, they often invent their own specific ways of articulating structures, designs, concepts, and decisions. What they need is a template that enables simple and efficient software architecture documentation. arc42 by Example shows how it's done through several real-world examples.

Each example in the book, whether it is a chess engine, a huge CRM system, or a cool web system, starts with a brief description of the problem domain and the quality requirements. Then, you'll discover the system context with all the external interfaces. You'll dive into an overview of the solution strategy to implement the building blocks and runtime scenarios. The later chapters also explain various cross-cutting concerns and how they affect other aspects of a program.

What you will learn

  • Utilize arc42 to document a system's physical infrastructure
  • Learn how to identify a system's scope and boundaries
  • Break a system down into building blocks and illustrate the relationships between them
  • Discover how to describe the runtime behavior of a system
  • Know how to document design decisions and their reasons
  • Explore the risks and technical debt of your system

Who this book is for

This book is for software developers and solutions architects who are looking for an easy, open-source tool to document their systems. It is a useful reference for those who are already using arc42. If you are new to arc42, this book is a great learning resource. For those of you who want to write better technical documentation will benefit from the general concepts covered in this book.

Table of Contents

  1. Acknowledgements
    1. Disclaimer
  2. Preface
    1. About the Book 
      1. About the Authors
      2. Learning Objectives 
      3. Audience 
      4. Approach 
      5. Conventions 
  3. Chapter 1
  4. I - Introduction
    1. I.1 What is arc42?
      1. Why arc42?
      2. Where to Get Additional Information
    2. I.2 Why This Book?
    3. I.3 What This Book is Not
    4. I.4 An Overview of Examples
      1. HTML Sanity Checking
      2. Mass Market Customer Relationship Management
      3. biking2
      4. DokChess – a Chess Engine
      5. docToolchain
      6. MiniMenu
    5. I.5 A table of arc42 Topics
  5. Chapter 2
  6. II - HTML Sanity Checking
    1. II.1 Introduction and Goals
      1. 1.1 Requirements Overview
      2. Basic Usage
      3. Basic Requirements
      4. Required Checks
      5. 1.2 Quality Goals
      6. 1.3 Stakeholders
    2. II.2 Constraints
    3. II.3 Context
      1. 3.1 Business Context
      2. 3.2 Deployment Context
    4. II.4 Solution Strategy
    5. II.5 Building Block View
      1. 5.1 HtmlSanityChecker (Whitebox)
      2. Contained Blackboxes
      3. 5.2 Building Blocks – Level 2
      4. Contained Blackboxes
      5. 5.3 Building Blocks – Level 3
      6. Contained Blackboxes
    6. II.6 Runtime View
      1. II.6.1 Executing All Checks
      2. II.6.2 Report Checking Results
    7. II.7 Deployment View
      1. Prerequisites
    8. II.8 Crosscutting Concepts
      1. 8.1 Domain Model
      2. 8.2 Structure of HTML Links
      3. 8.3 Multiple Checking Algorithms
      4. 8.4 Reporting
    9. II.9 Design Decisions
      1. 9.1 Checking of External Links Postponed
      2. 9.2 HTML Parsing with jsoup
    10. II.10 Quality Scenarios
      1. Quality Scenarios
    11. II.11 Risks and Technical Debt
      1. 11.1 Technical Risks
      2. 11.2 Business or Domain Risks
    12. II.12 Glossary
  7. Chapter 3
  8. III - Mass Market Customer Relationship Management
    1. III.1 Introduction and Requirements
      1. 1.1 Requirements Overview
      2. 1.1.1 Campaign Example: Mobile Phone Contract Modification
      3. 1.1.2 Campaign Configuration
      4. 1.1.3 Activities Subject to Charge
      5. 1.1.4 Additional Requirements
      6. 1.2 Quality Goals
      7. 1.2.2 Quality Goals (Scenarios)
      8. 1.3 Stakeholder
      9. 1.3.1 Special Case: German e-Health Card
      10. 1.3.2 Partner or Mandator-Specific Interface Details
    2. III.2 Constraints
      1. General Constraints
      2. Software Infrastructure Constraints
      3. Operational Constraints
    3. III.3 Context
      1. 3.1 (Generic) Business Context
      2. 3.1.1 Formal Business Context
      3. 3.1.2 Specific Business Context: Mobile Phone Contract Modification
      4. 3.1.2 Technical/Deployment Context
    4. III.4 Solution Strategy
    5. III.5 Building Blocks
    6. III.6 Runtime View
      1. 6.1 Import File
    7. III.7 Deployment View
      1. 7.1 Deployment Overview
      2. 7.2 Campaign-Specific Virtual Machine
      3. 7.3 Common Metadata Store (CoMeS)
      4. 7.4 Campaign Configuration Machine
    8. III.8 Cross cutting Concepts
      1. 8.1 Generated Persistence Based on the Domain Model
      2. 8.2 CSV Import/Export
      3. 8.3 Configurable File Filters
      4. 8.4 Rule Engine for Process and Flow Control
    9. III.9 Architecture Decisions
    10. III.10 Quality Scenarios
      1. Flexibility Scenarios
      2. Runtime Performance Scenarios
      3. Security Scenarios
    11. III.11 Risks
    12. III.12 Glossary
  9. Chapter 4
  10. IV - biking2
    1. IV.1 Introduction and Requirements
      1. 1.1 Requirements Overview
      2. 1.2 Quality Goals
      3. 1.3 Stakeholders
    2. IV.2 Architecture Constraints
      1. 2.1 Technical Constraints
      2. 2.2 Organizational Constraints
      3. 2.3 Conventions
    3. IV.3 System Scope and Context
      1. 3.1 Business Context
      2. 3.2 Technical Context
    4. IV.4 Solution Strategy
    5. IV.5 Building Blocks-Level 1
      1. 5.1 Whitebox biking2::api
      2. 5.1.1 bikes (Blackbox)
      3. 5.1.2 tracks (Blackbox)
      4. 5.1.3 trips (Blackbox)
      5. 5.1.4 locations (Blackbox)
      6. Files
      7. 5.1.5 bikingPictures (Blackbox)
      8. 5.2 Building Blocks – Level 2
      9. 5.2.1 bikes (Whitebox)
      10. 5.2.2 tracks (Whitebox)
      11. 5.2.3 trips (Whitebox)
      12. 5.2.4 locations (Whitebox)
      13. 5.2.5 bikingPictures (Whitebox)
      14. 5.2.6 galleryPictures (Whitebox)
    6. IV.6 Runtime View
      1. Creating New Tracks
      2. Fetching Biking Pictures from Daily Fratze
    7. IV.7 Deployment View
    8. IV.8 Technical and Crosscutting Concepts
      1. Domain Models
      2. Persistency
      3. User Interface
      4. JavaScript and CSS Optimization
      5. Transaction Processing
      6. Session Handling
      7. Security
      8. Safety
      9. Communication and Integration
      10. Plausibility and Validity Checks
      11. Exception/Error Handling
      12. Logging and Tracing
      13. Configurability
      14. Internationalization
      15. Migration
      16. Testability
      17. Build Management
    9. IV.9 Architecture Decisions
      1. Using GPSBabel to Convert TCX into GPX Format
      2. Using Local File Storage for Image and Track Data
    10. IV.10 Quality Scenarios
      1. 10.1 Quality Tree
      2. 10.2 Evaluation Scenarios
    11. IV.11 Risks
    12. IV.12 Glossary
  11. Chapter 5
  12. V - DokChess
    1. V.1 Introduction and Requirements
      1. 1.1 Requirements Overview
      2. 1.2 Quality Goals
      3. 1.3 Stakeholders
    2. V.2 Constraints
      1. 2.1 Technical Constraints
      2. 2.2 Organizational Constraints
      3. 2.3 Conventions
    3. V.3 Context
      1. 3.1 Business Context
      2. 3.2 Deployment Context
    4. V.4 Solution Strategy
      1. 4.1 Structure of DokChess
      2. 4.2 Game Strategy
      3. 4.3 The Connection of the Engine
    5. V.5 Building Block View
      1. 5.1 Building Block View-Level 1
      2. 5.1.1 Subsystem Text UI (Blackbox)
      3. 5.1.2 Subsystem Rules (Blackbox)
      4. 5.1.3 Subsystem Engine (Blackbox)
      5. 5.1.4 Subsystem Opening (Blackbox)
      6. 5.2 Level 2: Engine (Whitebox)
      7. 5.2.1 Search (Blackbox)
      8. 5.2.2 Evaluation (Blackbox)
    6. V.6 Runtime View
      1. 6.1 Move Determination Walkthrough
    7. V.7 Deployment View
      1. 7.1 Windows Infrastructure
    8. V.8 Technical and Cross cutting Concepts
      1. 8.1 Dependencies between Modules
      2. 8.2 Chess Domain Model
      3. 8.3 User Interface
      4. 8.4 Plausibility Checks and Validation
      5. 8.5 Exception and Error Handling
      6. 8.6 Logging and Tracing
      7. 8.7 Testability
    9. V.9 Design Decisions
      1. 9.1 How Does the Engine Communicate with the Outside World?
      2. 9.2 Are Position Objects Changeable or Not?
    10. V.10 Quality Scenarios
      1. 10.1 Utility Tree
      2. 10.2 Evaluation Scenarios
    11. V.11 Risks
      1. 11.1 Risk: Connecting to a Frontend
      2. 11.2 Risk: Effort of Implementation
      3. 11.3 Risk: Reaching the Playing Strength
    12. V.12 Glossary
  13. Chapter 6
  14. VI - docToolchain
    1. VI.1 Introduction and Goals
      1. 1.1 Problem Statement
      2. 1.2 Quality Goals
      3. 1.3 Stakeholders
    2. VI.2 Architecture Constraints
    3. VI.3 System Scope and Context
      1. Business Context
      2. Scope
    4. VI.4 Solution Strategy
      1. General Solution Strategy
      2. Individual Solution Strategy
      3. Export Tasks
      4. Version Control of Exported Artifacts
      5. Generate Tasks
    5. VI.5 Building Block View
      1. 5.1 Level 1
      2. 5.2 Level 2
      3. 5.2.1 Export Tasks
      4. Utility Tasks
      5. 5.2.4 Generate Tasks
    6. VI.6 Runtime View
    7. VI.7 Deployment View
      1. 7.1 Option 1: Installed the Command-Line Tool
      2. 7.2 Option 2: Git Submodule
      3. 7.3 Option 3: Docker Container
    8. VI.8 Cross cutting Concepts
      1. Automated Testing
    9. VI.9 Design Decisions
      1. DD1: Wrapped Plugins instead of Ruby Gems
      2. DD2: Visual Basic Script for EA Automation
      3. DD3: Support for Maven and Gradle
      4. DD4: Binary Gradle Plugins
      5. DD5: AsciiDoc as Basis
      6. DD6: Deployment Options
      7. DD6.1: Embedded
      8. DD6.2: Gradle Script Plugins
      9. DD6.3: Gradle Binary Plugins
    10. VI.10 Quality Requirements
      1. QS1: Confidentiality
      2. QS2: Security (besides Confidentiality)
      3. QS3: Repeatability
      4. QS4: Transformation Stability
      5. QS5: Performance
      6. QS6: Ease of Use
      7. QS7: Maintainability
    11. VI.11 Risks and Technical Debts
      1. TR1: Outdated Technology
      2. TR2: Missing Acceptance of the Docs-as-Code Approach
      3. TR3: Git Submodules
      4. TR4: Automated Tests (Technical Debt)
    12. VI.12 Glossary
  15. Chapter 7
  16. VII - macOS Menu Bar Application
50.17.63.57