Design project architecture, ships and javascript

    The story of what you need to consider to build a high-quality architecture of your project. How to make it unsinkable, and customers - satisfied.

    Below we look at real life examples and try to learn from the mistakes of others. And along the way we will compile a book of useful recommendations for a solution architect. In all stories - architectural tasks that begin with the primary requirements of the client and are accompanied by further debriefing.

    The article is based on a report by Alexey Bogachuk (solution-architect of EPAM) from the HolyJS 2018 Piter conference . Under the cut - video and transcript of the report.

    Approaches to building architecture and the role of the project architect

    Swam - know

    So said the sailors from the Swedish ship Vasa. Here they just swam, escaping from a sinking ship, which had just been launched from the stocks. What does Vasa have to do with it?

    Let's start with a small story that makes a completely different look at the approaches to building the application architecture and the role of the project architect.

    The Swedish king signed a contract with shipbuilding architect Henrik Hübertsson. Under the terms of the contract, Henrik had to build a flagship - the beauty of the Swedish fleet, the best ship in Europe. As the main sponsors, the king and the treasury participated in the coordination of all the main characteristics of the ship, in the end the order was formulated as follows:

    • the ship should be the largest in the Baltic Fleet: 70 meters long, 10 wide;
    • you need three decks, which will accommodate 300 soldiers;
    • he must have 64 cannons on board in two rows;
    • the building is given 3 years.

    Analogues of such a ship at this time did not exist. However, he himself also existed for a very short time, sinking in the midst of the celebration of its construction.

    When they tried to figure out why this happened, it was found that no deviations from the requirements were allowed. The size is the same, the number of guns is normal, the sailors on the decks are exactly the number that was required. Nevertheless, it was perfectly combined with the fact that the laws of physics did not allow such a vessel to hold out for any long time on the water.

    The following architectural failures of Henrik (which, by the way, could have cost him his life if he lived to court) are evident:

    • All conflicting restrictions were not balanced.
    • There was no risk management, because no one had built ships of such scale before.
    • Customer Relationship Management was also missing - Henrik did not have the courage to argue with the king.
    • Used the wrong technology built.
    • The architect agreed with the impossible requirements.

    As a result of these miscalculations, the ship "went to the bottom" at the design stage. The story is instructive, because it reflects the influence of the architecture cycle on the application being created. There are stakeholders who form goals, requirements, based on this, the project architecture is built, and then the project itself. A mistake at one of these stages can cost the entire project, and sometimes the head / work, Henrik Hübertsson will not let you lie.

    Powerful friends

    How many applications with the wrong architecture are dead before writing the first line of code?
    The cycle of influence of architecture on the project is as follows:

    From left to right:

    1. There are stakeholders, or stakeholders (in the case of a ship, this is the king and treasury).
    2. They have their own targets (the first ship in Europe).
    3. Objectives dictate requirements (specific characteristics of the future ship).
    4. Further drawings, schemes, the project are made.
    5. Construction on the project.

    An error at one of these stages may negate the future of your project.

    Handbook solution-architect

    We will look at real life examples and try to learn from the mistakes of others. At the same time, we will compile a book of useful recommendations for a solution architect. Henrik Hubertsson got burned by the fact that he didn’t have one like that.

    If we lived in the time of our hero, when mistakes in architecture were punishable by death, this book would have been written in blood.

    In all the stories will be given architectural kata (puzzles). They will be in a simplified form a request with the first customer requirements, the essence of the problem and the conclusion.

    Jimmy the Clockwork Story

    Customer requirements

    • Replace current UI-solution.
    • Introduce a new approach to the development and implementation of this solution.
    • We need the best user experience.
    • At the same time follow all the best practices.
    • Support for various platforms.

    What was done

    The requirements are very general, there is no specifics. It is not clear what to do with all this. At the same time, the development team is located in Minsk, and the customer is in Montreal. Due to the fact that there were sanctions between Belarus and Canada, they could not work directly with Canada. It was decided to work with the customer through an office in Dublin. Due to all these delays in time and mediation, the customer could not be contacted and finally determined the requirements, to make proposals for implementation.

    After a while, a certain Jimmy nevertheless began to answer questions and clarify requirements, the development of the project began. Jimmy willingly shared his advice, he took contacts and correspondence was conducted with him directly. Following the results of the presentation was made. It is time to show the results. There was a conference with important people from the customer, but, strangely, Jimmy was not among them, and no one knew who it was. Of course, everything turned out to be done absolutely not in the way the customer expected. The thing was that they did not know about any Jimmy in the company, it turned out that he was an ordinary developer and simply shared his experience and advice. He did not take decisions and, in general, did not have any relation to the project at all.

    Where is the mistake? In the very first stage of defining the architecture, stakeholders were incorrectly identified.


    Any architecture begins with the identification of stakeholders. In order to identify them, there are many approaches, we consider one of them - we will build a RACI-matrix.


    The abbreviation stands for: R - responsible, those who will implement; A - accountable decision makers; C - consulted (people of business) advising; I - informed, people who need to be informed. Each of the stakeholders should be attributed to a particular category. The matrix specifies the roles and tasks.

    By constructing such a matrix, one can understand who the stakeholders are.

    In addition, it was noted that among the stakeholders there are people who give false claims that lead the project away. In this case, it turned out that they were representatives of other vendors who were not interested in the project. But the RACI matrix is ​​not able to distinguish such customers, for this there is an Onion-approach.


    The onion approach is somewhat different from the RACI matrices.

    Its essence is that layers are built around the system, inside which certain customer faces are indicated. In this example, developers, DevOps, and content managers will communicate with the system itself. Slightly higher in abstraction - people from business. There are also external regulators: media, laws, etc. For example, to release an application in some countries, you must pass an audit conducted by a third-party company, it will reveal accessibility and other qualities required from the project, these are the requirements of external stakeholder.

    So, we write down in our architect’s reference book that the first and necessary stage is to determine the stakeholders.

    History: not fast enough

    The company had a client from trading, in this case the speed of transactions is very important. Based on this, a number of requirements were formulated.

    Customer requirements
    • Be faster than competitors

    • You need to make the transaction take place no more than 0.5 seconds.

    What did the

    project was done, but was unsuccessful. Why? Again, the requirements were not entirely correct. The goal was not to make transactions at a speed of 0.5 seconds, but to make them faster than a competitor. As a result, the speed was increased to 0.5 seconds, but the competitor at that time reached a figure of 0.4 seconds. We see an error in the definition of a business goal. Why does the customer need a system?

    A business goal is only the tip of the iceberg, behind it are business drivers, regulators, and internal goals of the company. Often they remain unknown. We are also more interested in technical goals, which includes a business goal. They are governed by business principles, for example, no one wants to sacrifice quality of work when implementing a technical goal, because this is a miscalculation in the long term. All this needs to be known and kept in mind when building architecture. As well as the fact that projects without a goal are dead initially.


    Even if you work in startups, the purpose of which, often, is to test new technologies, the use of new technology in a project is still not a business goal. The problem is that if the goal is to use new technologies, the project will constantly grow and require new unnecessary financial and temporary investments. Business goals should never be overlooked when designing an architecture.

    Useful recommendations for yourself can be found in the book “Discovering Requirements”, the authors are Ian Alexander, Ljerka Beus-Dukic.

    The story of how the horse pioneers milked

    The company that sells insurance has its own website. It works great and has a well-established functionality. It already has complex business logic.

    Customer requirements

    • It is necessary in addition to the site to make a mobile application that employees will use on their phones
    • The application must be offline.

    What was done

    Based on the requirements, it was decided to write on React Native. Development has begun. During the first call, clarifications and additions to the requirements were received:

    • Employees are issued to employees by the company, and they all work on Android.
    • Customer is only interested in offline mode.
    • Deadline is two months.

    Obviously, the task of dealing with a ready-made third-party product with complex business logic and writing a new one in two months does not fit into such a time frame. It was decided to use PWA (Progressive Web Apps).

    The experience of such work has already been. It was written not just PWA application, it was isomorphic. Services were reused from the server to the client, special wrappers were written, with the help of which it was possible to communicate with these services. A router was written that redirected all requests to the MongoDB database, on the client through the adapter worked with IndexedDB. Scheme - below.

    So, the problems were with the requirements that are not so simple. Consider an example of what the requirements are:

    There is a form, and we need to issue validation errors, if the wrong URL is entered, you need to display the page 404. What is wrong with the requirements? They talk about what the system should do. But for the architect it is more important what the system should be. If you delve into what the system should do, you can dive too deep into the details and go the wrong way. Such requirements are called functional, they are also called MoSCoW requirements. Words that are often in these requirements:

    All requirements that contain these words do not interest you. If we focus on such requirements, then a monolithic system will be built without any special architecture at all.


    An architect should focus on non-functional requirements, in particular, on restrictions and quality attributes. Next kata about it.

    The story of the white crow

    Customer requirements

    • Develop a separate service that converts and caches data in xml-format.
    • He must do this from a third-party legacy system.

    What they did

    Developed a good working service, did it on Node.js. This is how the system as a whole began to look schematically with the new service implemented.

    Obviously, Node.js here is a white crow, despite the fact that everything worked well.

    An error was detected during the transfer of services to customers who were not familiar with Node.js. This situation perfectly shows the role of identifying constraints for a project. What are the limitations?

    • Technical
    • Time and budget
    • Customer Development Stack

    Conclusion The

    architect is obliged to find out all existing restrictions that may affect the final product. Restrictions are architectural decisions that were made for you and for you.

    Next, go to the attributes of quality, we have a special interest in them.

    Quality attributes

    Very safe library

    There are a lot of quality attributes, just look at the list that Wikipedia gives us.

    At the heart of the story is the attribute "security." When you visit the library, you hardly expect, using a computer there, that you have to go through two-factor authorization, with the input of email, phone and verification code from the phone. Nevertheless, it happens. We see that the blind use of quality attributes can also be fraught.

    Phone in the forest

    What about performance? It is clear that there are no people who do not care about performance. Here is the script. Suppose a person wants to use a mobile application from his phone while in the forest. Thus, it affects our system, but not the whole, but the web interface. For example, he needs to get some data within three seconds. This is the performance script we need to get.

    It is these usage scenarios that an architect must assemble in order to build a quality system at the output. When we have a list of business requirements, quality-attributes, restrictions, we have learned all the stakeholders, we begin to address them in schematic diagrams. This addressing of attributes in schemas is called architectural tactics. Which architectural tactics can be applied to a system with a phone in the forest based on the available scenarios?

    • To improve the UX, so that the person seemed to have better performance.
    • Optimize resources (JS, CSS, images, fonts, etc.).
    • Produce caching.
    • Add service-workers, critical path.
    • Apply compression.
    • HTTP / 2.

    However, in the case of the phone in the forest, the UX and the critical path do not suit us right away. And again, tactics must be dictated by scenarios. This is the work of the architect, to choose from all the tactics needed in a particular case. But the application is not only the front end. Performance is also affected by the DNS, backend, database, and all this can also be optimized. There are many tactics to do this, but, again, the use of one or another depends on the use case.

    Let's try to use the CQRS pattern (command query responsibility segregation). The use of this pattern as a tactic even affects several layers of the application: both the back-end and the front-end.

    Suppose there is a very slow legacy database, we send a request there and after ten seconds we get a response. In addition, it is replicated and you need to make entries in both copies. We in the forest with a phone want to quickly read our data from this database. The pattern says that we need to separate read and write requests. Add a quick database to read. We add all the tools to synchronize this database with an existing one.

    The use of this kind of cumbersome tactics should be very clearly dictated by the requirements.

    So, we have applied some of the tactics. Run the application and see that it did not help, as there is no connection to the Internet. So we approached fault tolerance, which the solution-architect should take care of.

    The Steadfast Tin Soldier

    Nobody wants the application to fall steadily several times a day, everyone wants resiliency.

    In order for the application to work stably, the principle of fail fast can be applied:

    • Always verify the integration points in advance.
    • Avoid slow connections.
    • Check the entered data.

    Why use it, consider the example of Lie Connection (false connection). This is such a connection, which, perhaps, something and pings, but in fact does not work. This can happen between a client and a server, a database and a server, between services. Apply the Circuit Breaker pattern to it.

    So far so good, we do nothing. As soon as the timeout is exceeded, we switch to offline mode and after a certain period of time we make a new request. If the request again fails, we are again offline with an extended timeout. And if the request went well, we return to the online mode. Thus, this pattern allows both to verify the integration points and avoid slow connections.


    There are many approaches to ensuring resiliency. One of them is bulkhead (bulkhead, for example, in a submarine). Its meaning is that the application is written in such a way that it continues to work, even when an error appeared in one of its components.

    We have business logic in which we send data and get a response. We begin to frame it with our tactics, add validation, scale. An error occurs in business logic. We log it. As error information, we need the context in which it occurred. The trouble is that with such a frame of logic the context is unlikely to be preserved, therefore, we need to dump the memory. A memory dump is quite a big thing, and JavaScript errors are not so rare, therefore, it is quite expensive for computing resources. We need to divide the errors into critical and not so much and do a dump only for the first ones.

    Leaky bucket

    A strategy similar to the one described above is used in the Leaky Bucket pattern.

    We have counters for different types of errors. When an error occurs, an error counter of this type is incremented. On timeout, this counter decreases. But if the number of errors begins to go off scale, the counter does not have time to decrease and, figuratively speaking, overflows the bucket, after which we make a memory dump. Next, work on the error that caused the counter to overflow.

    Please note that the service that implements this pattern will also be wrapped in tactics, validation and will be scaled. This is how architecture is built.

    What do the green arrows mean? Different services interact with each other through various protocols, databases, other services.

    For those who want to learn more about fault tolerance patterns, the book "Patterns for fault tolerant software" by Robert S. Hanmer will be useful.

    We also recommend the book "Software Architecture in Practice", the authors - Len Bass, Paul Clements, Rick Kazman. In it you will learn about other attributes of quality and tactics of following them.

    Example for dessert


    • We want to offer existing client improvements for the current platform.
    • About 400 static sites have already been written on this platform.
    • The problem is that it is expensive and time consuming.
    • Content management is also expensive and long.
    • The platform is written in Drupal.

    Suppose you can use the following frameworks to solve these problems:

    We have already found interested parties. Need to define goals.

    The most global goal is to satisfy the customer.

    The business goal is to optimize customer costs (this is an interesting goal for the customer).
    Further, there are more specific goals: to reduce the time to launch a product to the market, to reduce the time of content management.

    Then the following restrictions are found:

    • It is necessary to write on Drupal, as the license and support for some time is purchased from the customer.
    • ReactJS and VueJS are used on the project, and the customer wants this to continue, the company is not ready to consider another framework.

    Having determined the quality attributes, we found out:

    • It is important to leave the possibility of supporting all 400 sites (maintainability).
    • It is necessary to introduce tests in order not to break the existing functionality (testability).
    • Reuse all existing content (re-usability).
    • Should work quickly (performance).
    • Accessibility for certain types of sites (accessibility).

    When we build architecture, you need to follow a certain model. Consider the C4 model. Build several charts.

    Context diagram:

    We define the roles of people who will work with the platform. In this example, these are visitors, developers, and content managers.

    Moving on to the container diagram:

    Based on the business context, there is a website that users are visiting. Developers work with the site generator, content managers work in the content hub. We do integration with third-party systems in the process of updating the platform.

    The component diagram looks like this:

    We see that developers make themes and components, and the Template Service works for them, which aggregates these developments. There is an integration point between the content hub and the site generator. There is also a template service that takes themes, components, and connects them with the data transferred from the content hub.

    How to speed up the content management work flow? It is necessary to allow content managers to work directly with the site generation module. Remembering all previous practices, we add the necessary approaches to the Template Service module. Note that Drupal is used exclusively in the content hub. We conclude that NuxtJS or Next.js frameworks, which are written on Vue.js and React.js, respectively, are suitable for static generation. As a replacement for integration points, it is beneficial to use GitHub and branches, so we come to the JAM approach. It stands for JavaScript, API, Markdown.

    It can be seen that the stack that was decided to use is different from the initial one. On the one hand, we used Node.js and some modern framework. We will leave Drupal for content management, but organizing it from our system, allowed us to integrate with the new CMS in the future, which may be more convenient and faster. Thus came to the understanding of Javascript, API, Markdown approach.


    You need to carefully select the final technology stack. This is what we write in our book of the architect.

    Final story


    Architect identified all interested parties, requirements, goals, restrictions. Next was made a project. Application development was conducted normally, but in the end the project failed.

    Why did this happen?

    The fact is that the project developers were not aware of the requirements, stakeholders, limitations and quality attributes. The development was carried out exclusively in the form of performing tasks in the task tracker, which ultimately led to the collapse of the entire project.

    Conclusion The

    architect must accompany the development of the project at an early stage in order to be sure that the development is carried out in accordance with the architecture designed by him.


    Summing up, let's write down a list of important things for the architecture. Print it and hang it in a prominent place. So that the ships that you built, kept on the water, and even better sailed in the right direction:

    • Any architecture begins with the identification of stakeholders.
    • It is necessary to take into account business goals in the design of architecture.
    • An architect should focus on non-functional requirements, in particular, on restrictions and quality attributes. He must understand what the application he is designing should be.
    • Architectural tactics should be dictated by usage scenarios.
    • You need to carefully select the final technology stack.
    • It is necessary to accompany the development of the project at an early stage so that it is conducted in accordance with the designed architecture.

    If you like the report, pay attention: a new HolyJS will take place on November 24-25 in Moscow , and there will also be many interesting things there. Already known information about the program - on the website, and tickets can be purchased there.

    Also popular now: