Disclaimer
I provide absolutely no guarantee, neither for the accuracy of this documentation nor for any property or feature of the software described here.
Do not use this software in critical situations or projects.
1. Introduction and Goals
Traqqr is a project for
-
letting me keep track of the energy usage of my electric car
-
evaluating and learning certain technologies:
1.1. Requirements Overview
From a functional point of view, Traqqr is a web application for keeping track of the energy usage of an electric car. The app that comes with my car does not provide such insights.
From a project perspective, I use Traqqr to study and evaluate technology, patterns and frameworks. The functional requirements aren’t too complex, leaving me enough room for attention to quality goals.
-
Logging in with a Google account.
-
Register a car for measuring.
-
This will issue an API key uniquely linked to that car.
-
Re-issue an API key for an existing car.
-
-
Register current battery capacity and mileage using a REST API.
-
Link two of such measurements to define a trip.
-
Combine two or more trips into a multi-leg trip.
-
View energy usage for any trip.
1.2. Main Quality Goals
The following list contains the most important quality goals for this application. The full list is in Quality Requirements.
| ID | Quality | Motivation |
|---|---|---|
QG01 |
Understandability |
Functional requirements should be simple and stay simple. This allows me to focus on the other goals (learning, experimenting) as well as writing quality code. |
QG02 |
Attractiveness |
The display should look good enough. |
QC03 |
Testability |
The architecture should allow easy testing of all main building blocks. |
1.3. Stakeholders
The following lists contains the most important personas for this application.
| Role/Name | Goal/Boundaries |
|---|---|
Developers |
Developers familiar with Java who want to learn about developing modern web applications without having to learn JavaScript/Typescript and an additional web application framework or two. |
Maarten Mulders (me) |
Improving my skills as an architect and a developer. Have some real-world, working sample code when discussing "traditional" web applications or Jakarta Server Faces. |
Users (including me) |
Having a convenient way to calculate energy usage of an electric car. |
2. Architecture Constraints
2.1. Technical Constraints
| Constraint | Background and / or motivation | |
|---|---|---|
Software and programming constraints |
||
TC01 |
Use of Java |
One of the goals is to learn and evaluate certain technologies. I don’t want to learn too much new things at the same, so I stick to Java as the programming language. |
TC02 |
Use of open source technology |
Third-party (not written by me) software must be available under an open-source license. It should not be necessary to download or purchase proprietary software in order to study or contribute to this project. |
Operating System Constraints |
||
TC03 |
OS independent |
Developing and running the project should not require any particular operating system. It should be possible on at least Windows, Linux and macOS. |
2.2. Organisational Constraints
| Constraint | Background and / or motivation | |
|---|---|---|
OC1 |
Team |
Primarily myself, Maarten Mulders. Contributions from others are welcome, but I don’t expect too many. |
OC2 |
IDE independent setup |
Developing and running the project should not require any particular IDE or editor. The project must be compilable on the command line via standard build tools (e.g., Apache Maven). |
OC3 |
Configuration and version control / management |
Code is stored in a public Git repository with a complete commit history. This repository will host the code as well as this documentation. |
OC4 |
Testing |
Use JUnit to prove functional correctness using unit tests and optionally integration tests. Use JaCoCo to ensure a high test coverage and use PiTest to ensure high quality of tests. Use Playwright to write functional integration tests. Use Pitest and the Stryker Dashboard to run resp. display mutation testing (results). |
OC5 |
Published under an Open Source license |
The source code as well as the documentation should be published under an Open Source license. |
2.3. Conventions
| Convention | Background and / or motivation | |
|---|---|---|
C1 |
Architecture documentation |
Structure based on the (English) Arc42 template. |
C2 |
Coding conventions |
The project uses the Palantir Java format. Formatting is enforced through and can be executed using Spotless. |
C3 |
Natural language |
English. The project and the documentation both target an international audience. |
3. System Scope and Context
This chapter describes the environment and context of Traqqr. Who uses the system and on which other system(s) does Traqqr depend?
3.1. Business Context
3.1.1. User
Somebody who drives an electric car and wants to have insight in how much electric energy that car(s) use.
3.1.2. Adapter
Electric vehicles do not connect directly to Traqqr. Instead, measurements must be retrieved from the vehicle. Depending on the vehicle, this can be done using manufacturer-provided API’s or hardware devices that connec to the car’s board computer. These measurements must be converted into a format that Traqqr expects before being uploaded to Traqqr.
3.2. Technical Context
The technical context of Traqqr is pretty simple. Polly runs as a web application and is accessible to users primarily using their web browser:
| Interface | Description |
|---|---|
HTTP (Web) |
Serves the (HTML) views to interact with a poll; this includes both viewing and voting. |
HTTP (API) |
Provide an Application Programmer Interface (API) to allow registering a measurement of a cars odometer and remaining battery capacity. |
4. Solution Strategy
Traqqr is a single deployable application using a relational database.
The architecture of Traqqr follows the ideas of hexagonal architecture. This means that its domain model is unaware of the technology that powers it. Each component lives in its own Maven module, which is also a Java module. This approach makes it easier to test a large part of the application logic in a fast and light-weight way [QC.OE.01].
Since Traqqr is designed as a Jakarta Enterprise Edition, all components can freely depend on API’s provided by that platform. The core of Traqqr is its Domain Model, which is completely agnostic of any other framework or library. It applies a few tactical patterns from Domain Driven Design. You will find Repositories, rich Entities and Value Objects.
Since the Traqqr is technology-agnostic, some parts cannot be implemented in the Domain. That’s why the Infrastructure provides implementations based on the selected technology stack. For instance, it provides implementations of the Repositories based on the Jakarta Persistence API.
The Web application is responsible for generating the web-based user interface. It uses Jakarta Server Faces to deliver fast, light-weight web pages rather than requiring users to download a large bundle of JavaScript [QC.PF.01].
The API is responsible for exposing a REST API that can be invoked by automation platforms (such as Home Assistant) to periodically register a car’s odometer mileage and battery capacity.
To bring it all together without introducing undesired dependencies, the Application module packages all these components together. It creates a Web Archive (WAR) using overlays, that can be deployed to any Jakarta EE 10-compatible application server [QC.OE.01].
5. Building Block View
Traqqr is divided in four main parts: the (Core) Domain, a Web application and a REST API that expose functionality from the domain, and the Infrastructure that provides technology-dependent implementations for components that live in the domain.
As outlined in the Solution Strategy, the domain model must be unaware of the technology that powers it. It is the responsibility of the Infrastructure module to provide the actual implementations for concerns like persistent storage of domain entities.
10. Quality Requirements
10.1. Quality Tree
The following list contains the quality goals for this application. The goals with an identifier between square brackets correspond with one of the Main Quality Goals.
| ID | Quality Category | Quality | Description | Scenario |
|---|---|---|---|---|
QC.US.01 |
Usability |
Attractiveness [QG02] |
I want to use Traqqr to look good. |
|
QC.US.02 |
Usability |
Ease of use |
Users should not have to register an account before being able to use the application. |
[SC1] |
QC.PF.01 |
Performance |
Responsiveness |
Displaying a page should take less than 2 seconds. |
|
QC.OE.01 |
Operational & Environmental |
Runtime agnosticism |
The solution should work on any Jakarta EE 10 compliant application server. |
|
QC.MS.01 |
Maintainability & Support |
Understandability [QC01] |
Functional requirements should be simple and stay simple. This allows me to focus on the other goals (learning, experimenting) as well as writing quality code. |
|
QC.TS.01 |
Testability [QC03] |
The architecture should allow easy testing of all main building blocks. |
||
QC.SC.01 |
Security |
Confidentiality |
Users should only be able to see the energy usage of the car(s) that they drive. |
10.2. Quality Scenarios
| ID | Scenario |
|---|---|
SC1 |
Log in using Google |