Software Achitecture
1 INTRODUCTION
The chapter gives an overview of the design.
1.1 Purpose and coverage
This document is for the developers who care about the technical details. This document will go over our stack, gives a brief explanation of each technology, why we chose them, and how we are using them.
1.2 Product and environment
The product is Tukko, short for Traffic Visualizer. Tukko is a full-stack web application that shows general data and hotspots about Finnish traffic.
Tukko is running on CSC (IT Center for Science) servers, where we have two Linux virtual machine instances for production and development environments. As a modern web application, Tukko will support modern browsers for all operating systems.
1.3 Definitions, notations and abbreviations
- CI/CD Pipeline: Continuous Integration and Continuous Delivery (CI/CD) automates the manual human intervention traditionally needed to get new code from a commit into production
- CSC – IT Center for Science Ltd.: A Finnish company that provides IT support and modeling, computing and information services for academia, research institutes and companies in Finland
1.4 References
List references to other sources (documents, standards, manuals, style guides, etc.) in alphabetical order by reference. References include the name, version, date, and where they can be found. Examples include:
- documents referred to (eg definition)
- documents related to the system or its construction
- additional information
- (coding) style instructions.
- If the design does not cover the entire specification, it is mentioned here. At the same time, it will be clarified what other documents at the design stage exist.
- For example, the design of a database or user interface may have been detached as a separate document).
1.5 Overview of the document
This document provides a comprehensive overview of the architecture for the software development project. It outlines the fundamental structure, design principles, and key components of the system.
This section describes the structure, content, and organization of the document; what is covered in any chapter. This is especially important if the reader is not used to reading design documents. If the first chapter is entirely on the same page as this section (1.5 overview) or is very short, it does not need to be mentioned in this section, but you can start with the things in Chapter 2. The contents of each chapter are described more than just browsing the table of contents. Possible appendices are also described here, e.g., appendices 1-4 contain class diagrams of the main parts of the system.
2. SYSTEM OVERVIEW
The chapter presents an overview of the system to be implemented, an introduction to the customer's environment and application area.
2.1 Description of the application area
Tukko runs across 4 docker containers, each dependency having its own container. CPU must be able to run virtualized software, which in 2023 should be most processors from the last decade.
2.2 Software Environment
As the entire stack is dockerized, all your environment needs is docker support. Linux servers were used in the project.
2.5 Key boundary conditions for implementation
Mention important boundary conditions. They are often customer requirements. These may include, but are not limited to, implementation hardware, software, laws or settings, response times, criticality, accuracy, security, and programming language. Mention may also be made here of instructions on the language of the document and the code comments, variables and functions, etc.
2.6 Agreements and Standards
If design methods, description methods, documentation models, etc. according to standards and / or different agreements are used, then they are mentioned. The use of finished parts and the rules for naming them may also be described (if necessary, reference to the annex or its own document). Various directives, regulations and guidelines are also mentioned if they affect the design. Here they can be mentioned by name and the whole source is presented in detail in section 1.5. We will also comment on the confidentiality of the project material, if it is appropriate to mention it. Issues related to confidentiality include: distribution, storage, disposal of old versions, etc.
3. DESCRIPTION OF THE ARCHITECTURE
Application architecture diagram
Deployment Diagram
3.1 Design principles
Our team's strategy for improving the application revolves around three main principles: aesthetics, performance, and usability. We've noticed that many previous versions of traffic visualizers lacked in user experience, featuring unattractive designs and slow performance.
Drawing from our observations of past projects, we're keenly aware of the frustration caused by long loading times and sluggish interactions. Therefore, our team prioritizes optimizing the visualizer's performance through efficient data processing, caching, and a scalable architecture.
Additionally, we recognize the importance of making the application easy to use. By organizing information thoughtfully and offering clear navigation, we aim to reduce the learning curve for users, ensuring intuitive interaction with the visualizer.
3.2 Software architecture, modules and processes
Frontend
REACT
React is a very popular JavaScript framework that allows developers to create more complex and scalable web applications.
React was requested by Combitech, but the team was also excited to learn React! In the professional field, React has been a main stay for years, so our "value" in the job market goes up for learning React.
VITE
Vite is a powerful development server. It has multiple features that make development easy, such as live reload, module bundling and so on.
When building an web application, Vite also makes some performance improvements by converting your entire project into basic HTML, JavaScript and CSS.
NGINX
Nginx is an HTTP server that can serve your website to the world. The frontend that Vite builds gets fed to a container running Nginx, which then serves our web application.
Backend
NODE.JS WITH EXPRESS
https://nodejs.org https://expressjs.com
Node.js is a JavaScript runtime, meaning you can run JavaScript code on your computer like you would a regular program. More commonly JavaScript is limited to running in browsers.
With Express, you can create a server that runs Node.js, and is a very popular solution for APIs. Our backend will serve Digitraffic data to our frontend, and Express is a good tool for that.
MONGODB
MongoDB is an object-based database solution and is built and used with JavaScript. You might see a theme here, it's just JavaScript all the way down. The structure of a MongoDB database is much more flexible as opposed to the more common relational databases.
With the data format of MongoDB also supporting JSON natively - the same format that Digitraffic and most other APIs offer - it works very well for our purposes.
REDIS
Redis is another database solution we are planning to use. The benefit of Redis over MongoDB is that it supports in-memory storage. This gives massive improvements in looking up data from the database. Each datapoint is also relatively small compared to hardware of today, so we can store quite a bit of data at once.
Redis is used over MongoDB when the user asks for live data and more recent archival data, but older data is transferred to MongoDB.
General technologies
TYPESCRIPT
TypeScript is a superset of regular old JavaScript. The code is practically the same, and in a minimal setup can literally be the same as JavaScript code.
The benefits of TypeScript though allow developers to debug their code easier, trust their code, and avoid the more careless bugs, as giving your code types lets your tools tell you when you are doing something wrong.
DOCKER
Docker is used to containerize everything. Frontend is its own container, while each element of the backend gets their own containers.
How containerization helps, is that it avoids the problem of "it works on my machine", meaning if a developer has tested the container locally, it will also work on our servers.
Docker also makes the stack more secure, as Docker allows the administrator to create strict and secure configurations on how accessible each container is to the public. Our backend for example is completely inaccessible to the outside world, but the frontend can still communicate with it.
3.3 Database Architecture
The database structure is fairly simple, as it is just one database that holds everything. MongoDB supports objects as it's model, so the following is a paste of the used interface in our code to show the structure.
interface Sensor {
stationId: number,
name: string,
shortName: string,
timeWindowStart: string,
timeWindowEnd: string,
measuredTime: string,
unit: string,
value: number
}
interface Station {
id: number,
tmsNumber: number,
dataUpdatedTime: string
sensorValues: Sensor[]
}
interface StationData {
id?: ObjectId,
dataUpdatedTime: string,
stations: Station[]
}
This section describes the files and databases, e.g. division into files and / or databases, interfaces between files and databases, organization of files and databases, database software used (if any), security, recovery, backups, maintenance, upkeep. The structure of the files and databases is presented (eg tables, ie relational descriptions, if the implementation is done with a relational database). In the design document, the data content descriptions of the specification document are converted to physical database descriptions. For example, when using a relational database, any inheritance relationships and many-to-many connections in the data content description of the definition document are decompressed. In addition, the indices required for navigation are defined. Based on the description, you should be able to write the SQL create table and create index statements needed to create the database. The database solution and files describe:
- Solution overview, databases, files and their interfaces
- other software or systems using the database
- database support software (eg backups, recovery, testing)
- databases and files
- database structure (class diagram with explanations)
- Descriptions of the fields in the file records and columns in the database tables:
- field name or identifier
- field meaning
- field length and shape
- allowed values type
- processing or calculation rules
- relationships with other information
- upgrade criteria and methods
- space requirements
- maintenance considerations
- backup aspects
- security considerations.
3.4 Error and Exception Procedures
In unexpected crashes in any of the containers, they will restart themselves. In case of multiple rapid restarts, the containers will stop trying to avoid infinite loops.
CSC Servers handle their errors fairly gracefully and redistribute virtual computing accordingly.
4. MODULE / CATEGORY / PROCESS DESCRIPTIONS
The reading structure of this chapter is designed according to the architecture of the program: If a one-level breakdown is sufficient, the method presented here is used (4.1 Module X, 4.2 Module Y…). For example, if a program is divided into packages that contain multiple categories, you should make a separate section for each package, with each category described in the subsections. Things common to all classes in a package are described at the beginning of the chapter, and if the package has an interface, it is also described here. In large-scale projects, a separate design document is written for the internal structure of each package or subsystem. Each module describes its function, interfaces with other parts, interface and implementation aspects. The technical details must be explained in such detail that the description can be used to test the module as a black box test.
4.1 Module X (each module has its own section 4.i)
4.1.1 Overview
Module name: Module type: (class, function, process, package, subsystem, library) Overview: A brief description of the module - why it exists, what it does. Customers: which / what type of parts of the system need the services of this part (in the case of a general purpose component this item is missing). Dependencies and interfaces to other modules: Briefly describe how a module takes advantage of other modules and services in its environment (can often be combined with an overview).
4.1.2 Interface in general
The services provided by the module and the common features of the interface functions (eg error handling) are described in general terms. In some cases, it is useful to give examples of using the module by describing the communication between the client and the module, for example as an event sequence diagram. Mention is also made here of any Standard and similar definitions that may appear outside the interface, possible capacity restrictions and their modification, status information stored by the module, etc.
4.1.3 Interface Functions
Each interface function is described separately in its own subsection: * Function name * Function parameters and return value * Action: what the function does * Prerequisites: describes what the state of the program must be before calling the function. * Post-conditions: describes the state of the program after the function call (eg side effects). * Error situations: exceptions and other error situations, operation when preconditions do not apply when called
4.1.4 Implementing the module
If necessary, instructions for implementation may be provided, for example: * Thoughts on the implementation of the internal data structures of the module. * Thoughts on the algorithms used. * Known potentially reusable components. * If the module is complex, pseudocode, activity diagrams, etc. can be used. If necessary, a separate module design document can be made.
4.1.5 Error handling
Describes error and exception handling at the module level.
5. FINISHED COMPONENTS AND SPECIAL TECHNICAL SOLUTIONS
If there are finished parts, ie external components, then such are described: * where they are obtained * where they are placed * use * other essentials (so that someone else can compile or add the application). If some things differ from the usual working methods of the project. "Solutions that deviate from standard industry practice" that a person in the industry might not immediately guess. For example, the following, if necessary: * security, safety * backups * recoveries * maintainability * flexibility * portability or portability. Especially if there is some special or unusual way to do something. Implementing tools can also be mentioned here, if it is indeed important to tell already at this (design) stage (rare and not recommended, for example B compiler version 2.77 which supports D library 4.56). The project plan contains detailed information on the implementation tools. For example, can a program automatically recover from power outages or operating system "crashes"?
6. SOLVED SOLUTIONS
Considered, but rejected, solutions should be recorded with their rationale in an appropriate chapter or section with dates. Thus, the next reader of the document sees that something has been thought about as well. Also, if you are reading a design document yourself in six months, it may be difficult to remember what things have been considered when making the system.
At the end of the project, the rejected solution options are collected at the end of the project plan
7. FURTHER DEVELOPMENT IDEAS
Gather useful ideas that come to mind along the way, but which are not planned or implemented in this project; for example due to lack of time, lack of money, lack of resources or skills and competences. For example, ideas for further development should be numbered to make it easier to refer to them later. The date and the name (letters) of the proposer will help in the follow-up, especially if the source is outside the project, if after one year the project unexpectedly receives funding for further development. At the end of the project, this chapter is collected at the end of the project plan. The ideas for further development can also be presented as a separate appendix, which can be appended to other project documents if necessary.
8. ITEMS STILL OPEN
The figure is unofficial and should no longer be at the end of the project. This can be used to mark issues that are open during the life cycle of the document, ie that need to be resolved, so that they can be clarified before the document is finally completed.
FUTURE ADDITIONS
Software architecture thought like Zachman
- Framework and 4+1 View Model
- Reference Model for Open Distributed Processing (RM-ODP)
- Enterprise viewpoint --> Business Case
- Information viewpoint -- >
- Computational viewpoint
- Engineering viewpoint
- Technology viewpoint
- Link Jari Suni here :)
Original Source http://www.cs.tut.fi/ohj/dokumenttipohjat/pohjat/suunnittelu/hytt_drsuunnittelu.doc
Thank you for original authors!