Skip to main content

How to describe the architecture of a software product? [Resolved]

I'm working on my Master thesis in CS for a company which does user interfaces in the field of embedded devices. Part of the thesis is to develop a library for integrating a certain device and handling the information it provides in Qt. The manufacturer of the device provides a driver library written in C that allows communicating with the microcontroller's firmware via I2C messages. What I do is wrap around the driver library with my Qt C++ code and also integrate the device's features in the Qt framework so that it can be used with a variety of Qt-based applications (including QML).

So far I have written many notes and detailed API documentation (using doxygen). The problem is that I have no idea how to properly format all the information so that it "looks good" in a thesis. Obviously putting some doxygen-generated documentation doesn't make sense since 1)it's way too detailed and 2)doesn't exactly give a formal overview of how things are structured and work together.

From what I know I have to describe at least the following aspects of the software product I'm developing:

  • Technology(ies) - which technologies I have used. I have split my project in a library part (which provides the device management and conversion of the data to a more friendly format plus its integration in the Qt framework), tests and also a component part which uses the library but offers ready-for-use widgets that can be easily integrated in any Qt-based project that uses widgets.
  • Patterns - what software design patterns I have used (MVC, Singelton, Factory, Observer etc.). The problem here is that there are many, many patterns out there and there is a known inconsistency when it comes to which pattern is what exactly (alone the MVC pattern is very famous for it - pick three books from different authors and there is a very high chance that the descriptions of this pattern vary greatly!). Personally I work following the principle "XYZ makes sense to me hence I will use it", which probably many of you will find too broad. :D
  • Information flow - mostly sequence and flow diagrams here: if user does action X how does the device and the rest of the system respond to it.
  • Data management - I'm using data containers such as arrays, vectors, hash tables etc. All this is related to storing and using the data my library processes from the device.

I doubt that this is enough or even correct that's why I'm asking for help. I was unable to find a step-by-step tutorial that I can follow. I also don't know how deep I have to go. I have asked my professor about the hardware-level stuff and he said that he doesn't want to see that in the thesis and that I should concentrate on what I am developing. However this restriction only helps a little bit since alone Qt as a framework has a huge and complex structure. For example if I use a QVector3D do I have to actually describe in detail what this is and how it's managed or can I assume that a simple "A container for 3D vectors" would suffice? Frankly, we have studied various software architecture related things (patterns etc.) but we were never shown how to actually describe a software product in a formal way. It was mostly short lab reports and API documentation + some evaluation statistics about performance.

Asked January 11, 2017
Posted Under: Programming
2 Answers

Consider using 4+1 Architecture view to describe architecture of your software.

Summary of the views is given below:

Development view: An implementation view from software developer perspective. UML Diagrams (such as package diagram) could be used to represent this view.

Logical view: It provides functional view describing functionality that the system provides to end-users. UML diagrams (such as class diagrams, and activity diagrams) could be used to represent the logical view.

Physical view: It reveals a system engineer's point of view. It is also referred as the deployment view. Deployment diagram could be employed to describe the view.

Process view: It captures the dynamic aspects (concurrency, runtime behavior, etc.) of the system. Activity diagrams are suitable for the view.

Scenarios: Scenarios (or use cases) describe sequences of interactions between objects and between processes.

Answered January 11, 2017
Thanks, this looks like it covers everything in a nice way. I will give it a shot. For now I'll mark your answer as the accepted one. – rbaleksandar yesterday
 CanDoerz  1 week ago

You need diagrams. A good diagram is better than a wall of words, and can be pasted into any document (including a thesis). UML class diagrams are an obvious starting point. Add other UML diagrams if they are useful to you - such as package diagrams, use-case diagrams or sequence diagrams. Maybe use other non-UML types of diagrams if you want.

Once you have the diagrams, you can write the words around them.

Answered January 11, 2017
Your Answer