How to write an architecture manual (2)

according to the first article, we know that a general section of the architecture Design Manual should look like this :

• Document Overview: Contains the project background, project objectives, document version information, target readers, reference documents, noun interpretation and other general documents will have chapters;
• Overall architecture: mainly from the entire IT layer describes the location of the system, and the relationship between the surrounding system;
• Logical architecture: The division of the internal function module and the description of the function of each module and the relationship between them;
• Interface design: Including the interface design between the system and the Internal function module interface design;
• Data architecture: The data flow relationship between the system and the upstream and downstream systems, as well as the key data table design and data management strategy of the system;
• Technical architecture: What technical capabilities are needed to implement this architecture, and what are the reuse capabilities and risks;
• Deployment architecture: How the system is deployed, what is required on the network topology, what requirements are required on the hardware server, how many units are needed, and whether the server parameters need to be optimized;
• Non-functional design: performance, high availability, scalability, maintainability, security, portability, and more.
• Other notes: such as special constraint conditions, risk considerations, schedule requirements, policy restrictions, environmental impact, etc.;

So in turn, we'll look at what issues each chapter needs to focus on during the review process, and what the people who write the architecture design specification need to provide:

(i) Documentation overview

To explain the structure design specification itself, it is necessary to clarify the background of this document, that is, why there is this documentation, the scope of the content of the document, the intended audience, including which needs to be synchronized reference documents, which need to explain the terminology, can be divided into two levels of title to write, Content form such as: This document is XX system XX period project architecture design/upgrade/change, mainly from the overall architecture, logical architecture, interface design ... And so on each aspect elaborated the system each structure dimension the content, expects the reader to be the project management personnel, the structure management personnel, the operation and maintenance personnel and so on, in the compilation process reference xx demand book, XX structure design norm and so on; The review will generally focus on:

Whether the purpose of the document and the scope of the content are described from an architectural perspective;

Reference documents otherwise referred to the "User Requirements Specification", business knowledge documents, etc.;

Explain whether the terminology is interpreted for non-generic and non-it abbreviations;

Whether the whole chapter is clear on the document as a whole, so that readers have a general understanding of the entire article.

(b) Overall structure

Describe the system in the framework design of the overall thinking and policy, such as the adoption of a hierarchical structure, b/s structure, service, data separation, while in the design process of some constraints, such as Network access constraints, development norms constraints, open source product agreement type, more importantly, as a whole structure, It is necessary to use this system as an internal opaque whole, to clarify what external systems interact with it, and what is the need for interaction with specific external systems? such as through the message bus to obtain customer information, through the enterprise content management access to unstructured data, through the CRM to obtain customer information, and the system as the center of the entire interactive diagram, that is, the overall architecture diagram. The review will generally focus on:

Whether the design scheme is clearly expressed and consistent with the actual design content;

Whether the corresponding constraints are real and specific, and have the possibility of checking;

Whether the system needs to interact with the system from the overall architecture diagram, and what the purpose of the interaction is;

If the interaction between the system is correct, whether the external system can satisfy the interaction, such as obtaining customer information through CRM, is it feasible to obtain the Organization information?

(iii) Logical architecture

The logical architecture is concerned with how the system is divided into different parts and how each part interacts, which defines what logical elements the software system consists of and the relationships between the logical elements (layers, subsystems, modules, etc.), the interface and the interaction mechanism [method Invocation, RMI, message]. Therefore, the logical architecture diagram needs to be clear about which modules the system contains, how the modules interact, and the purpose of the interaction is to achieve which business needs. At the same time, for the specific function module, need to explain clearly the business significance of functional modules. The review will generally focus on:

Does the logical architecture diagram list the functional modules and their interactions between modules;

Whether the modules listed in the diagram are described in detail gives the reader a complete understanding of why the module is available and what business requirements it includes.

(iv) interface design

The design of the interface in architecture includes two aspects, on the one hand refers to the external interface relationship between the system and the external system, it is necessary to all the interfaces with the external system, to explain in detail the name of each external interface (such as XX data push interface), the system name of the interaction (such as ODS), Interactive methods (such as WebService), interaction categories (such as background async), interface descriptions (such as the system through this interface to obtain XX business data from the ODS), on the other hand refers to the internal function modules within the system internal call relationship, strictly speaking, this part belongs to the logical structure of the part, The same needs to be based on the invocation of each function module, in turn, to explain the name of each internal interface (such as Reporting Service interface), the keynote module (that is, the active internal invocation of the function module such as presentation Module), the service module (that is, the module providing services, such as the report module), Interface description (such as the presentation module through this interface to obtain report data from the report module to achieve decoupling between the modules), generally speaking, internal interface calls belong to the code level, if you need to deploy a standalone module and the use of remote invocation, need to do special instructions. Interface is an embodiment of the system complexity, is the embodiment of high cohesion, low coupling design principle is a very important aspect, the review will generally focus on:

external and internal interface whether all examples, whether according to the above-mentioned elements of the interface dimensions are explained;

For the service provider, it is indeed possible to provide the appropriate services as described by the interface.

(v) Data architecture

Data processing is the ultimate goal of the system, the system in the process may require external data assistance, while the system processing data may also need to provide other systems to use, so the most important thing for the data architecture is to clarify the system processing data in the entire business data flow chain location, What systems upstream have to supply the system, downstream which systems need to use the data of this system. In addition, according to the system to the data processing, need to explain the system design of key tables, data initialization of how to do, how to do data redundancy, backup how to do, etc., the review will generally focus on:

Whether the relationship between the data of the system and the upstream and downstream systems is clearly described from the point of view of business data flow;

According to the business processing of the system, the key Entity data tables and their corresponding ones are designed, and whether they can be fully covered;

There is no data volume estimation, data initialization, data archiving method, backup strategy, etc.

(vi) Technical framework

The key technical capabilities of the system in the implementation process are described from a technical point of view, with core technical components, including mature business suites and open source technology products. If the business suite needs to explain the use restrictions, upgrade support, etc., if it is open source technology needs to explain the open source agreement requirements. Can be based on the mode of hierarchical architecture, such as the presentation layer used to jquery, Flex and so on, the logic control layer used to spring, JSON, and so on, this must be technically, for the specific use of components, must explain the components of the version, function, applicable scene. Of course, reusability is the key to the technical architecture, whether it is using the previous components or open source products, through reusability to reduce the duplication of resources, so in the technical components need to emphasize the importance of reusability, the review will generally focus on:

Whether the key technology is explained, and the maturity and applicability of the technology can be clearly stated;

Whether the use of certain technologies is in conflict with similar technologies commonly used in enterprises, such as the use of Redis in other systems in the enterprise, and the use of memcached in this system;

(vii) Deployment architecture

Make it clear that the system is divided into several physical parts, each need several servers, the server is a common service cluster mode or a service to provide a standby Master-slave mode, or is responsible for writing multiple sets of read-and-write separation mode, from the network level, The location of the system in the entire enterprise network environment, such as an outreach or DMZ or intranet area. For the needs of the server, you need to describe the server hardware and software configuration information, such as the hardware of several cores, hard disk size, network port number and network bandwidth requirements, software requirements of the operating system, version requirements, system and software parameters tuning settings, etc. whether the need to pre-install third-party software, the required software version, Deployment instructions, and so on. The review will generally focus on:

Is it possible to understand the physical deployment of the system in several parts from the deployment architecture diagram;

The collaboration of the servers between the deployment parts;

To the hardware server model, configuration, quantity and so on is clear;

Whether the network area of the overall deployment is clear;

Whether it is necessary to explain the tuning of the relevant parameters and the special deployment requirements.

(eight) non-functional description

The non-functional features of the system include performance, high availability, scalability, maintainability, security, portability, in general, for performance or security requirements of the system, you can separate it into a one-level chapter to write, such as real-time analysis of class system requirements for performance, transaction class requirements for security, Performance and security can be described as separate chapters, and other non-functional functions can be handled similarly. In the process of writing, can have the primary and secondary respectively elaborated, but must from the realization of the system, that needs to describe clearly what the system did design or optimization to meet the performance, the design of the verification mechanism to ensure security, how to ensure the availability of the cluster or hot standby deployment, how to say the past state implementation can be extended, etc. How these designs are implemented in the system. That is, from what the system does to meet the non-functional perspective, rather than explaining what the specific non-functional requirements are. The review will generally focus on:

The description of non-functional is from the perspective of how the system is implemented rather than the requirements of the system;

Each kind of non-function can find the corresponding demand point from the demand, and match with the business reality;

The system does not contradict the architecture of the system itself, and the structure can be satisfied by reasonable adjustment.

Non-functional review needs to be based on the business characteristics of different systems to review, the overall principle is to say that the implementation of the requirements, after all, architecture design is to guide the implementation of the follow-up system construction.

(ix) Other notes

This section mainly describes some of the supporting constraints or environment, such as constraints, risk considerations, progress requirements, policy constraints, environmental impact, etc., according to the actual foreseeable situation. such as high-level on the overall system requirements, development resources constraints, business environment impact, personnel knowledge structure. The review process generally does not focus on specific matters unless the system has special requirements.

Above is the entire structure design specification review content, is also each chapter preparation guidance idea, I according to in the actual work some experience rough summary, not necessarily comprehensive, but to the entire establishment will have some help, and everybody discusses the study together.

How to write an architecture manual (2)