We often need to explain how an application works to new members of the team, colleagues we work with, application leaders, etc. How can we clearly explain how the entire application is built and works?

UML(Unified Modeling Language)

UML represents software components in the form of diagrams. It can be divided into two main categories:

  • Behavioral UML diagram
  • Structural UML diagram

The examples below are not a complete list of chart categories, but just a few that I think are commonly used

Behavior UML-activity diagrams

Modeling the collaboration between one activity and another can be thought of as a higher version of a flowchart. For example, you can add swimming lanes to describe the logic of sales meeting new customers

See the activity chart for explanation

Behavior UML-state machine diagrams

The behavior of the entity depends not only on the input, but also on the previous state. Like the order delivery state machine

See the state machine diagram

Behavior UML-sequence diagrams and communication diagrams

Take reading overdue as an example, sequence diagram and communication diagram can be used respectively to make the following statements: Sequence diagram: used to illustrate the cooperative communication between objects

See the sequence diagram

Communication diagram: Used to show how objects communicate with each other

See communication chart for details.

Communication diagrams vs sequence diagrams: they are semantically the same, showing the same information. The difference is that sequence diagrams are displayed by time, while communication diagrams are displayed by space

Structure UML-class diagram

Class diagrams illustrate the relationships among classes, attributes, methods and objects in object-oriented systems. For example, a class diagram for an order system might look like this:

See the class diagram

Structure UML-component diagrams

Component diagrams decompose the entire system into high-level abstractions (functions), with each component responsible for a certain thing in the system. An ordered component might do this

See component diagram

Improper use of UML can cause problems

When the system description is too large, it may not be very readable

4+1 View model

  • Logical View: The main focus is on features, what features it provides and how the code is designed to support them;
  • Development View: Focuses on the organizational structure of the code, such as modules, models, packages;
  • Process View: Focuses on the running state of the system, such as: communication, concurrency, performance, etc.
  • Physical View: Focuses on the hardware on which the code runs, such as topology;
  • Scenarios: Mainly through a few use cases to help explain the architecture;

You can see the 4+1 view model in more detail in this figureAs shown in the4 + 1 view

C4 model

Four different granularity levels are used to describe the software architecture. The implementation details of the “inner layer” can be seen by zooming in from the top layer and corresponding to the corresponding level according to the appeal

You can imagine looking at a map, you can see Asian countries at the highest level, and then you can zoom in to see provinces, and then you can see more details, and that’s the basic idea of C4

  • System context diagram: the coarsest granularity, representing the relationship of the system to users and other systems, in most cases, a system owned by a development team;
  • Container diagram: Containers represent an application or data store. Each container can be deployed and run independently.
  • Component diagram: The combination of all functions encapsulated by a good interface, which in the C4 model is a unit that cannot be deployed independently;
  • Code: Shows how components are implemented in code;

See the C4 Models website, C4 Models for Software Architecture, and Simon Brown’s C4 share

ADR Architecture Decision Records

Keep a log of why you chose this architecture at the time. You can format this log yourself, or refer to the Github ADR instructions

reference

documenting-software-architecture