In the first article in this series, I described a principle I consider fundamental: value does not come from data itself, but from our ability to transform it into useful information for making decisions. When we try to turn that idea into a real product, however, a second problem quickly emerges.
It is not enough for the software to work. It must continue to work as it grows.
And this is where architecture stops being a theoretical discussion and becomes a sequence of very concrete decisions.
In the project I am developing, this has been the most interesting transition: starting with an application capable of processing data and progressively turning it into a local desktop product, with distinct components, a controlled lifecycle, reliable persistence, and reproducible packaging.
Domain First, Technology Second
One of the choices I have tried to avoid from the outset is designing the system around frameworks.
Before asking which technology to use, I tried to identify the main responsibilities:
- data acquisition and parsing;
- validation and normalisation;
- persistence;
- statistics calculation;
- interpretation of behaviours;
- exposure through APIs;
- presentation to the user;
- management of the desktop application’s lifecycle.
Only after defining these boundaries did it become natural to assign a clear responsibility to each component.
The resulting architecture is deliberately simple:
Angular → local HTTP API → Spring Boot → SQLite
with Electron acting as the desktop runtime and system orchestrator.
It is not a distributed architecture in the traditional sense, but it maintains a very clear separation between presentation, application logic, and persistence.
Why Keep a Real Backend in a Desktop Application
One of the first architectural decisions was not to move all the logic into Electron or directly into the frontend.
The application engine remains a Java backend based on Spring Boot.
This means that, even though the product is distributed as a desktop application, it still maintains very clear internal boundaries.
This choice brings several important benefits.
The frontend does not know about the database.
The database does not know about the UI.
The statistical engine does not depend on Electron.
And the desktop shell does not contain the domain logic.
In other words, the fact that the product is a desktop application is a distribution characteristic, not something that permeates the entire architecture.

From the Logical Model to the Real-World Runtime
Defining the logical boundaries correctly is only part of the problem.
When software has to be distributed on a real machine, we also need to understand where the different components actually live and what governs their operation.
The installed package contains several elements:
- the Electron main process;
- the Angular frontend;
- the Spring Boot backend;
- a dedicated Java runtime;
- the resources required by the application.
Alongside these is a separate, persistent space for user data:
- the SQLite database;
- logs;
- backups;
- configuration.
This separation is intentional.
The application can be updated or reinstalled without treating user data as part of the software itself.
Installed software ≠ user data
This distinction becomes essential when moving from the development environment to real-world distribution: the product can evolve, but the data must remain identifiable, preserved, and governed according to criteria different from those applied to the installed code.

Electron as an Orchestrator
Electron must not become the place where application logic is moved.
Its role is much more specific: to orchestrate the components required for the application to work as a single desktop product.
At startup, it must therefore:
- verify that only one instance of the application exists;
- locate the required resources;
- determine an available local port;
- start the Java backend;
- verify that the backend is genuinely ready;
- open the application window;
- manage process shutdown correctly.
This makes Electron a kind of supervisor for the local runtime.
The distinction matters: Electron knows how to start and stop the system, but it must not know the domain rules.
Backend Startup and Readiness
Starting a process does not mean that the process is already ready to work.
This may seem like a trivial distinction, but it is very important when a desktop application depends on a local backend.
The Java process may have been created successfully while Spring Boot is still initialising the application context, checking the database, or applying migrations.
Opening the frontend too early therefore risks sending requests to a service that exists as a process but is not yet available as an application.
The solution is to introduce a genuine readiness check.
After starting the backend, Electron periodically queries a dedicated local endpoint and shows the UI only when it receives a valid response.
“The Java process has started” and “the backend is ready to accept requests” are not the same thing.
This small distinction makes startup deterministic and allows timeouts, errors, and initialisation failures to be handled explicitly.
A Dynamic Port, Not a Magic Port
During development, using a fixed port is natural.
In a desktop product installed on machines we do not control, however, that port may already be in use.
Relying on an arbitrarily chosen number introduces a hidden dependency on the user’s environment.
For this reason, the launcher can identify an available local port at startup and pass it explicitly to the backend.
The same information is then used by the frontend to build the address of the local APIs.
The result is a runtime that does not depend on a hard-coded port and reduces the likelihood of collisions with other software on the machine.
The general principle is simple: configurations that depend on the execution environment should be determined or validated at runtime, rather than treated as universal constants.

Local Persistence: SQLite and Flyway
For a local desktop application, SQLite is a particularly compelling choice.
It does not require a separate database server, keeps the data in a single file, and makes it possible to distribute the product without asking the user to install or configure additional infrastructure.
Operational simplicity, however, does not remove the need to govern schema evolution.
When the software changes, the data model may change too.
For this reason, I retained Flyway in the desktop runtime as well.
Migrations become part of the application lifecycle: at startup, the backend checks the schema version and applies the necessary changes in a controlled manner.
In this way, the local database is not a detail left to each individual installation, but a versioned component of the product.
Installed Software and User Data Are Two Different Things
Another important step was physically separating what belongs to the application from what belongs to the user.
The installed software contains the executables, runtime, and resources required for operation.
The database, logs, backups, and configuration must instead live in a dedicated persistent location for the user.
This separation makes it possible to update or reinstall the application without confusing the software lifecycle with the data lifecycle.
It also clarifies concerns such as backups, troubleshooting, and future migration strategies.
The principle is simple:
Software can be replaced. User data must survive.
Local APIs, but Real APIs
The fact that the frontend and backend run on the same machine is not a good reason to weaken the contract between them.
The APIs therefore remain real HTTP APIs, with explicit endpoints and responsibilities.
This keeps the frontend independent of the backend’s internal implementation and prevents Electron from becoming an alternative channel through which domain logic can pass.
Communication remains simple:
Angular → HTTP → Spring Boot
even though everything happens through the machine’s local interface.
This boundary offers another benefit as well: it makes the components easier to test and leaves open the possibility of changing the distribution model in the future without rewriting the domain.
Single Instance and the Application Lifecycle
A desktop product must also handle situations that are easy to overlook during development.
What happens if the user launches the application twice?
If each instance started its own backend, we could end up with duplicate processes, different ports, and multiple components attempting to access the same database.
For this reason, the main process must acquire a single-instance lock.
If an instance is already active, the second one does not create a new runtime: instead, it brings the existing application to the foreground.
The same care is required during shutdown.
Closing the window does not simply mean closing Electron: we must ensure that the backend process is also stopped correctly and that no orphaned processes remain.
The product lifecycle therefore becomes an explicit responsibility:
startup → readiness → use → shutdown.
It is precisely these details, almost invisible when everything works, that progressively distinguish a prototype from a distributable product.
Packaging: When the Project Becomes a Product
As long as an application is run from the development environment, much of its complexity remains hidden.
The real shift in perspective comes when the software has to be installed on a machine where we cannot take anything for granted.
The product must bring with it everything it needs to work.
In my case, this means distributing together:
- the Electron application;
- the Angular frontend;
- the Spring Boot backend;
- a dedicated Java runtime;
- the resources required at startup.
The user should not need to know about this composition.
From their perspective, there is a single application: they install it, launch it, and use it.
Packaging therefore becomes part of the architecture, not simply the final command in the build pipeline.
If the product requires manual configuration, undeclared external dependencies, or technical knowledge from the user, some of the complexity we thought we had solved has simply been moved outside the code.
Modularity Without Over-Engineering
As the project grows, a question inevitably arises: how much should we modularise?
It is easy to fall into one of two extremes: on one side, a monolithic application in which every component knows everything; on the other, an extremely fragmented structure built in anticipation of needs that may never arise.
I preferred a progressive approach: clearly separate the responsibilities that exist today, while maintaining boundaries that allow them to be extracted or replaced tomorrow if necessary.
There is no need to introduce a new architectural layer simply because it might be useful in the future. What matters is avoiding today’s decisions making tomorrow’s unnecessarily expensive.
Do not introduce architectural complexity to demonstrate technical sophistication. Introduce it when it solves a real problem.
Modularity does not necessarily mean multiplying processes, services, or repositories: above all, it means governing dependencies and responsibilities.
Testing Architectural Decisions Too
Tests should not protect only algorithms and functionality.
Some of the product’s most important properties concern its architectural boundaries.
For example:
- the frontend must communicate with the backend through the intended contract;
- the database must be initialised and migrated correctly;
- the application must be able to choose an available port;
- the UI must not be shown before the backend is ready;
- a second instance must not create a second runtime;
- closing the application must not leave orphaned processes.
These behaviours tell us something important.
Architecture is not merely what we draw in a diagram.
It is a set of properties that the system must continue to respect as it changes.
For this reason, wherever possible, architectural decisions should also become verifiable.

The Real Objective: Making Change Affordable
Ultimately, the point is not to build the most sophisticated architecture possible.
It is to build a system that can change without forcing us to reconsider everything we have already created each time.
A prototype primarily optimises the speed with which we can validate an idea.
A product must add a second dimension: the ability to continue evolving.
This is where many apparently technical decisions take on a broader meaning.
Separating the domain from the runtime.
Separating software from data.
Making contracts explicit.
Governing the lifecycle.
Automating migrations.
Testing boundaries.
Avoiding premature complexity.
They are different choices, but they all answer the same question:
how much will it cost to change this decision when the context is different?
Organise software today in a way that keeps the cost of tomorrow’s decisions reasonable.
This is probably the most interesting lesson I am taking from the project.
Architecture is not there to predict the future perfectly.
It is there to prevent every future change from becoming a rewrite.
And it is a principle that applies far beyond software: in projects, teams, and organisations, a good structure does not eliminate change.
It makes it manageable.
