Skip to main content

5.1 Overall System

Ar42 specifications helper

Contents​

Here you describe the decomposition of the overall system using the following glass box template. It contains

  • an overview diagram

  • a motivation for the decomposition

  • black box descriptions of the contained building blocks. For these we offer you alternatives:

    • use one table for a short and pragmatic overview of all contained building blocks and their interfaces

    • use a list of black box descriptions of the building blocks according to the black box template (see below). Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).

  • (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the glass box. Since there are so many ways to specify interfaces why do not provide a specific template for them. In the worst case you have to specify and describe syntax, semantics, protocols, error handling, restrictions, versions, qualities, necessary compatibilities and many things more. In the best case you will get away with examples or simple signatures.

<Overview Diagram>

Motivation

: <text explanation>

Contained Building Blocks

: <Description of contained building block (black boxes)>

Important Interfaces

: <Description of important interfaces>

Insert your explanations of black boxes from level 1:

If you use tabular form you will only describe your black boxes with name and responsibility according to the following schema:

NameResponsibility
Black Box 1 <Text>
Black Box 2 <Text>

If you use a list of black box descriptions then you fill in a separate black box template for every important building block . Its headline is the name of the black box.

<Name black box 1>​

Here you describe <black box 1> according the the following black box template:

  • Purpose/Responsibility

  • Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.

  • (Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, ….

  • (Optional) directory/file location

  • (Optional) Fulfilled requirements (if you need traceability to requirements).

  • (Optional) Open issues/problems/risks

<Purpose/Responsibility>

<Interface(s)>

<(Optional) Quality/Performance Characteristics>

<(Optional) Directory/File Location>

<(Optional) Fulfilled Requirements>

<(optional) Open Issues/Problems/Risks>

<Name black box 2>​

<black box template>

<Name black box n>​

<black box template>

<Name interface 1>​

…

<Name interface m>​

5.1 Motivation for this decomposition​

Separation of concerns – UI logic lives in a lightweight Vue SPA, while all business rules sit behind a strongly-typed Spring API.

Independent lifecycle – Front-end, back-end and database each ship as their own Docker image (docker-compose.yml) so they can be rebuilt, restarted or scaled separately without breaking the others.

12-factor compliance – configuration via env-vars and stateless containers prepare the project for future cloud moves, yet the footprint remains small enough for a single VPS.

Testability & evolvability – the backend’s hexagonal modules (see level-2 component diagrams) make domain logic unit-testable and ready for extraction into separate services when needed.

5.2 Contained building blocks (black-box view)​

NameResponsibility
SPA FrontendDelivers all screens, calls the REST API, subscribes to WebSocket topics, and enforces basic field validation.
Backend APIImplements domain use-cases (RFQ, Quote, Provider …), authentication/authorisation, notification dispatch, integration stubs for future PO & IMS links.
Relational DBSingle MySQL schema that persists every aggregate (users, providers, trucks, RFQs, quotes, evaluations, …).

5.3 Important system interfaces​

InterfaceFrom → ToProtocol & FormatNotes
REST API v1Frontend → BackendHTTPS, JSON, OpenAPI 3.1CRUD for every aggregate; JWT bearer token required.
WebSocketBackend → FrontendWSS, STOMP, JSONReal-time in-app notifications (RFQ status, new quote, etc.).
JDBCBackend ↔ DatabaseMySQL nativeConnection pool (Hikari), flyway migrations at startup.
Package / FeatureDiagram file (PlantUML)What it shows
security-auth-user (security, users, accesses, registration_request)component_security_auth.pumlFilters, JWT provider, user/role entities, registration workflow
rfq-module (request_for_quotations, request_for_quotations_items, status)component_rfq.pumlControllers, services, status matrix, number generator
quote-module (quote)component_quote.pumlQuote controller/service/repository, status logic
provider-module (provider, notification)component_provider.pumlProvider CRUD, search spec factory, notification listeners
fleet-module (truck, antenna, technical_specification)component_fleet.pumlTruck CRUD, spec validator, antenna services
evaluation-module (evaluation)component_evaluation.pumlEvaluation controller/service, category & rating handling