Here are the first three chapters of my arc42-based architecture documentation. Next time we are doing the architecture constrains and maybe the system scope. It is necessary if I want to make it right, but if you are bored, please wait for 2–3 posts, when we will start describing the system structure 🙂

Introduction and Goals

This project is an effort of establishing a development workflow via practical product development.

There are two main requirements for the project:

• The product should be a working and entertaining for a cat autonomous toy.
• Components, processes and libraries of the project must be developed to be reusable in other projects.

The project is based on the following principles:

• Architecture-oriented
  • Develop the right architecture using architectural best practices
• Result-oriented and minimalistic
  • Progress over perfection
• Integration-oriented
  • Reusing existing libraries, projects, etc. Minimum development of individual pieces
• Reusable in my other projects
  • It should be done automatically with a good architecture. But I want to make several special decisions to make the project easy to transfer to my another robotic project.

Quality Goals

Stakeholders

There are some decisions to make. These decisions are basically our tools preparation. Let’s start from the frameworks

Frameworks

Architecture frameworks:

• arc42 - describes the structure, tools are up to implementors, can be used with other frameworks
• 4+1 - Generic and can be not enough for complex systems, can be used with other frameworks
• C4 model - lacking the structure, often used with arc42
• UML - SW oriented language. No documentation structure can be used with other frameworks. But as a visual framework it is very developed and widely used.
• RM-ODP - for Distributed Processing. It seems not very suitable for the project
• Systems Modeling Language (SysML) - extension of UML to support not only SW systems. Should be
• TOGAF - popular framework for enterprise architecture. To be honest, looks too complicated for me and my project.
• ArchiMate - a visual addition to TOGAF. These folks are super developed and have a very steep learning curve, so I will skip them for this time.

My choice is: 

🎉 arc42 + SysML 🎉

Having them two, I will have a text guidance + visual guidance. Also, I already have a quite comprehensive experience with UML, so it should help the process.

Subjects of Development

Now let’s consider what we are going to create. In the book Clean Architecture, the author provides a picture like this to illustrate what is the clean architecture:

We should start from defining the core and delay the rest decision as long as possible. The outer layer should be dependent on the inner one.

Next Step

Next time, I will define some basic entities we will be working with and will describe the first chapters of the arc42 template, such as:

1. Introduction and Goals
2. Constraints
3. Context and Scope
4. Solution Strategy

Okay, to build an architecture I need some model or workflow. I could come up with something, but it contradicts to one of the project principles - “integration first”. I don’t want to reinvent new things if they are already invented. So let’s see what we have…

• c4model
• ArchiMate
• arc42
• 4+1 Architectural View Model
• UML (but it is rather a tool, then an architecture dev framework)
• a lot of other stuff!

Also, there are several nice articles for orientation in all this ocean

• https://www.workingsoftware.dev/software-architecture-documentation-the-ultimate-guide/
• https://icepanel.io/blog/2023-02-28-7-modelling-languages-for-software-architecture
• https://medium.com/tradeling/how-to-design-software-architecture-c39eb5481a07

I need some time to think about it, so the next step is postponed for the next time… But the next time we will have the guidance (I’ll explain my choice) and we will do some pretty stuff!

With this post, I start my new robotic project. This project will have several important features:

• Architecture-oriented
  • Develop the right architecture using architectural best practices
• Result-oriented and minimalistic
  • Progress over perfection
• Integration-oriented.
  • Reusing existing libraries, projects, etc. Minimum development of individual pieces
• Reusable in my other projects
  • It should be done automatically with a good architecture. But I want to make several special decisions to make the project easy to transfer to my another robotic project

What is the project about?

It is a cat companion. A simple robot that can move around, avoid big obstacles and move a stick for playing with a cat.

What is the first step?

I’m starting with the architecture development. I will try to make the most abstract decisions first, leaving the implementation details to the very end.

The first step is development of the use cases. Basically, there are 3 actors for this robot - a cat, a cat owner, and me, a robotic developer. As a developer, It is important for me to have a moving platform (legs, wheels, etc.) reusable by other projects, so it is also reflected in my use case diagram:

That is it for now. Next time we will probably define the system requirements based on each use case.