Chemaclass - architecture

Introducing a New Tech Stack

2023-04-14T00:00:00+00:00

To introduce a new tech stack for the entire team, it’s important to bring “why?” and a strategy to make it happen among the team because it will affect everyone.

Why that new tech stack? #

To decide whether to use a new tech stack or not, remember that it is a team decision, according to the standardization and maintainability of the project when introducing such a new tech stack. But, most importantly, what problem do you want to solve by introducing it? Is it because it is “cool”? Or is there an actual “necessity” that this tech helps you with?

The direction of the technology #

When proposing adopting a new library, framework, or entire new technology, an important aspect to consider is to be aware of its background and the direction where they are moving forward.

What is the motivation for that tech, and why are you considering introducing it in your current stack?

Coupling and dependencies #

When adopting new technologies in our daily business, it’s not rare that we tend to couple ourselves with them. This makes it harder later to roll back if, after a while, we regret that decision.

Don’t get me wrong, learning and experimenting with new technologies is great, but introducing it in your daily work is another story because it will affect the whole team. So we need to be more careful with this.

The focus of the conversation #

What does this new tech contribute to the project?
What problem do we want to solve by introducing it?
Can we solve that problem with our current tech?
If we already have a similar tech, do we want to have a mix of both?
What are the tradeoffs when using it vs. not using it?
Is it worth the incremental complexity over time?
What is the team strategy to onboard everyone if we aim to use it?

Architectural Decision Records (ADRs) #

Whatever the outcome, you should write it down as an ADR to revisit it as time passes. An ADR will record your team’s decisions regarding the pros and cons, among any other arguments you have found together, to decide what to do and why.

ADRs are useful to understand old decisions and keep them in the version control, in the same project if possible. They are helpful for the current team, but also for new joiners.

Recipes for Decoupling

2022-11-28T00:00:00+00:00

What is coupling, and why is it bad? What is decoupling, and how to do it efficiently? This book is a compilation of strategies to decouple your domain code from those infrastructure details, so you can enjoy a healthier system in the long run.

This book will teach you how to create PHPStan rules from no knowledge, and then it will guide you across many decoupling opportunities like, for example:

web framework
cli frameworks
form validation
orm and database
test framework

Read more about the book: matthiasnoback.nl/book/recipes-for-decoupling/

Buy it here: leanpub.com/recipes-for-decoupling

Modern Software Engineering

2022-06-29T00:00:00+00:00

This book presents software development as an engineering practice at every level. To master software engineering, we must become experts at learning and managing complexity.

Optimize for learning #

To optimize for learning, the book presents five behaviors to consider:

Working iteratively
Feedback
Incrementalism
Empiricism
Being Experimental

The main idea is to work on small steps, collect feedback, and adjust.

Optimize for managing complexity #

The book presents other five ideas to manage complexity:

Modularity
Cohesion
Separation of Concerns
Information Hiding and Abstraction
Managing Coupling

We need to manage the complexity of our systems.

Tools to support engineering in software #

Going deeper into some ideas that were already discussed in the book, like:

Testability
Deployability
Controlling the variables
Continuous Delivery

A great video explaining the core ideas behind this book by his author:

Team Topologies

2022-03-31T00:00:00+00:00

Team Topologies focuses on how to set up dynamic team structures and interaction modes that can help teams adapt quickly to new conditions, and achieve fast and safe software delivery.

Team structure #

High cohesion: Group related things together.
Loose coupling: There must be clear boundaries between the teams.
Cognitive load: It’s like the RAM of the team. The team can burn down if you load with more than the team can handle.

In order to avoid bottleneck teams, you need to make sure their cognitive load is not very high.

Conway’s Law #

The organization structure will influence the architecture of the team.
Conway’s Law says that organizations will design systems that copy their communication structure.
In other words, there will be no focus on the optimal architecture for the project.
First you need to define the architecture of the project, and then form the teams.

Team-First Thinking #

Who is in the team matters less than the team dynamics.
When measuring performance, teams matter more than individuals.
Team = group of 5-9 who work towards a shared goals as a unit.
- Check Dunbar number.
Forming a team takes from 2 weeks to 3 months.
Cognitive load is the total amount of mental effort being used in the working memory.
3 Types of cognitive load:
- Intrinsic: Fundamentals of the problem space. Example: programming language.
- Extraneous: Environment related. Example: how to deploy.
- Germane: Special attention is required. Example: business domain.
Heuristics:
- 3 types of domain: Simple, complicated, complex.
- If the domain is too big, split it into subdomains.
- One team, either:
  - 2-3 simple domains.
  - 1 complex domain.
  - Avoid 2 complicated domains, better split the team.
Define a Team API:
- Code: endpoints, libraries, clients, …
- Versioning.
- Documentation.
- Practices and principles.
- Communication tools.

Team Topologies #

Instead of structuring teams according to know-how or activities, organize teams according to business domain areas.

Success of topology depends both on team members and surrounding environment, teams and interactions.
Split responsibilities to breakdown silos.
Types of dependencies: Knowledge, task, and resource.
Four types of teams:
- Stream-aligned: deliver features, projects, products to the market asap.
- Enabling: grow the capabilities for the Stream-aligned team(s).
- Complicated-subsystem: reduce the cognitive load of the Stream-aligned team(s).
- Platform: make the Stream-aligned team(s) autonomous.

Team Interactions #

Collaboration. Work closely between teams with different skill sets.
X-as-a-Service. Clear ownership, small cognitive load.
Facilitation. Helping to clear impediments, focus on quality interactions between other teams.

Principles of package design

2020-11-12T00:00:00+00:00

Apply design principles to your classes, preparing them for reuse. You will use package design principles to create packages that are just right in terms of cohesion and coupling, and are user- and maintainer-friendly at the same time.

The first part of this book walks you through the five SOLID principles that will help you improve the design of your classes. The second part introduces you to the best practices of package design, and covers both package cohesion principles and package coupling principles. Cohesion principles show you which classes should be put together in a package, when to split packages, and if a combination of classes may be considered a “package” in the first place. Package coupling principles help you choose the right dependencies and prevent wrong directions in the dependency graph of your packages.

What You’ll Learn #

Apply the SOLID principles of class design
Determine if classes belong in the same package
Know whether it is safe for packages to depend on each other

Domain-Driven Design Distilled

2020-09-10T00:00:00+00:00

Domain-Driven Design Distilled brings DDD to life. Whether you’re a developer, consultant, or customer, it will help you understand it, so you can benefit from its power.

This book delivers powerful results in practice, which is why developers worldwide are rapidly moving to adopt it. This is an accessible guide to the basics:

What is DDD?
What problems does it solve?
How does it work?
How to quickly gain value from it?

You’ll learn how to segregate domain models using the powerful Bounded Contexts pattern, to develop a Ubiquitous Language within an explicitly bounded context and help domain experts and developers work together to create that language.

How to use Subdomains to handle legacy systems and integrate multiple Bounded Contexts to define team relationships and technical mechanisms.

Domain-Driven Design Distilled brings DDD to life.

Advanced Web Application Architecture

2020-08-16T00:00:00+00:00

This book helps you get your web applications back in shape. It contains many techniques for decoupling from infrastructure (like the framework or the database).

“The best guide that brings your coding and architecture skills a level up. All the modern PHP features combined with the elegance of a well-designed modular design.”

In Part 1 we unlock a collection of design patterns which help you establish a clean separation between core and infrastructure code. Part 2 shows how these design patterns resonate at a higher level with architectural concepts like layers, ports and adapters (a.k.a. Hexagonal architecture). The book finishes with a discussion of testing strategies and design trade-offs.

What you’ll learn #

Separating mixed code into core and infrastructure code by refactoring into patterns.
Dividing your code into layers, and making a clear distinction between an application’s ports and adapters.
Testing decoupled applications.

Buy the book: https://leanpub.com/web-application-architecture

Design patterns for modernizing legacy code bases #

Symfony 5

2020-02-20T00:00:00+00:00

This book, written by Symfony’s creator, lays out a pragmatic approach to developing web applications with Symfony 5: from scratch to production. Whether you are discovering Symfony for the first time or refreshing your knowledge, this practical guide provides the definitive introduction to modern Symfony applications.

Clean Architecture

2018-06-04T00:00:00+00:00

Code design principles (SOLID) #

Single Responsibility: a class should have one, and only one, reason to change. Or the new version: a module should be responsible to one, and only one, actor.
Open-closed: a class should be open for extension but closed for modification.
Liskov’s Substitution: objects in a program should be replaceable with instances of their subtypes without altering the correctness of that program.
Interface Segregation: many client-specific interfaces are better than one general-purpose interface.
Dependency Inversion : one should depend upon abstractions, not concretions.

Component principles #

Component cohesion #

Reuse/Release Equivalence Principle: classes and modules (i.e. a component) reused together should be released together. They should have the same version number and there should be proper documentation such as changelogs.
Common Closure Principle: classes that change together should be grouped together, and vice versa. The single responsibility principle at component-level.
Common Reuse Principle: don’t force users of a component to depend on things they don’t need. The Interface Segregation Principle at component-level.

Component coupling #

Acyclic Dependencies Principle: no cycle in the dependency graph. Cycles couple components and, among other things, force them to be to released together. Use the dependency inversion principle to break cycles.
The Stable Dependency Principle: less stable components should depend on more stable components. Depend on the direction of stability.
Stable Abstractions Principle: stable components should be abstract, and vice versa. An example of an abstract stable component is a high-level policy which is changed by extension following the open-closed principle.

Architecture principles #

Setting boundaries #

Boundaries are lines that separate software elements. They separate things that matter from things that don’t, i.e. high-level components from low-level components. If a high-level component depends on a low-level component at the source level, changes in the low-level components will spread to the high-level component. Therefore, we place a boundary between the two, using polymorphism to invert the logic flow. This is the Dependency Inversion Principle in the SOLID principles.

Separating layers #

We can identify four main layers, although the number may vary:

Entities: objects containing critical business logic. For example, a bank could establish that no loans are granted to customers not satisfying some credit score requirements. Entities may be shared across apps in the same enterprise.
Use-cases: app-specific business rules. For example, the sequence of screens to execute a bank transfer.
Interface adapters: Gateways, presenters and controllers. For example, this layer will contain the MVC architecture of the GUI and also objects that transform data between the format of the database and the use-cases.
Frameworks and drivers: web frameworks, database, the view of MVC.