All notes
SoftArchitec

# Basics

## Diagrams

### Tools

• ArgoUML
• IBM® Rational® ClearQuest® 是一种应用生命周期管理 (ALM) 软件，通过提供灵活的变更和缺陷跟踪、可定制流程、实时报告和生命周期可跟踪的功能提高了软件开发生命周期的可视化和可控化。

Voxxed. Infoq. A number of typical approaches to communicating software architecture suffer from the following types of problems:

Colour-coding is usually not explained or is often inconsistent.
The purpose of diagram elements (i.e. different styles of boxes and lines) is often not explained.
Key relationships between diagram elements are sometimes missing or ambiguous.
Generic terms such as "business logic" are often used.
Technology choices (or options) are usually omitted.
Levels of abstraction are often mixed.
Diagrams often try to show too much detail.
Diagrams often lack context or a logical starting point.


#### C4 model

The static structure of your software with NoUML:

1. Context diagram: the highest level diagram showing your system as a box in the centre, surrounded by other boxes representing the users and all of the other systems that the software system interfaces with. Detail isn't important here as this is your zoomed out view showing a big picture of the system landscape. The focus should be on people (actors, roles, personas, etc) and software systems rather than technologies, protocols and other low-level details. It's the sort of diagram that you could show to non-technical people.
2. Containers diagram: a high-level diagram showing the various web servers, application servers, standalone applications, databases, file systems, etc that make up your software system, along with the relationships/interactions between them. This is the diagram that illustrates your high-level technology choices. Focus on showing the logical containers and leave other diagrams (e.g. infrastructure and deployment diagrams) to show the physical instances and deployment mappings.
3. Components diagrams: a diagram (one per container) showing the major logical components/services and their relationships. Additional information such as known technology choices for component implementation (e.g. Spring, Hibernate, Windows Communication Foundation, F#, etc) can also be added to the diagram in order to ground the design in reality.
4. Class diagrams: this is an optional level of detail and I will typically draw a small number of high-level UML class diagrams if I want to explain how a particular pattern or component will be (or has been) implemented. The factors that prompt me to draw class diagrams for parts of the software system include the complexity of the software plus the size and experience of the team. Any UML diagrams that I do draw tend to be sketches rather than comprehensive models.

##### Benifits and principles in C4 model

A single diagram can quickly become cluttered and confused, but a collection of simple diagrams allows you to easily present the software from a number of different levels of abstraction.
Different levels for different audience.
For example, there are other stakeholders and consumers, a "context" diagram is enough.
A diagram showing the containers is particularly useful for people like operations and support staff that want some technical information about your software system, but don't necessarily need to know anything about the inner workings.

Grady Booch has a great explanation of the difference between architecture and design where he says that architecture represents the "significant decisions", where significance is measured by cost of change.

• Titles: short and meaningful, numbered if order is important.
• Lines: explicit line style and arrows, and add annotations to lines to provide additional information.
• Layout: sticky notes and index cards better than drawn boxes, esp. early on.
• Labels: be wary of using acronyms.
• Colour: explicit color coding.
• Orientation: like users at the top and database at the bottom.
• Shapes
• Keys: explain shapes, lines, colors, borders, acronyms, etc.
• Responsibilities: adding responsibilities to boxes to provide a nice "at a glance" view (Miller's law, 7+/-2).

Each group needs to agree upon the vocabulary, terminology and abstractions they are going to use. The notation can then evolve.