6. Runtime View

Ar42 specifications helper

Contents

The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:

• important use cases or features: how do building blocks execute them?

• interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?

• operation and administration: launch, start-up, stop

• error and exception scenarios

Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevance. It is not important to describe a large number of scenarios. You should rather document a representative selection.

Motivation

You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view).

Form

There are many notations for describing scenarios, e.g.

• numbered list of steps (in natural language)

• activity diagrams or flow charts

• sequence diagrams

• BPMN or EPCs (event process chains)

• state machines

• …

<Runtime Scenario 1>

• <insert runtime diagram or textual description of the scenario>

• <insert description of the notable aspects of the interactions between the building block instances depicted in this diagram.>

<Runtime Scenario 2>

...

<Runtime Scenario n>

---

...

Identity Access management (IAM)

Login request

Notable aspects

Category	Observation
Security	• Password verified twice: first with PasswordEncoder.matches, then again by Spring Security’s AuthenticationManager. • Access & refresh tokens are minted after both verifications succeed.
Session hygiene	Before storing the new pair, all previously active tokens of the user are marked loggedOut=true (token rotation).
Performance	Everything is synchronous; no I/O other than a single DB round-trip (findByEmail) and two inserts into TokenRepository.
Error handling	Wrong password goes through the same code path but fails at PasswordEncoder.matches, keeping timing differences minimal.

Authenticated Request

Notable aspects

Category	Observation
Security context	JwtAuthenticationFilter enriches the UsernamePasswordAuthenticationToken with an AuthInfo object (userId, providerOpsCode, roles). No controller or service ever parses the JWT directly.
Horizontal security	Method-level authorisation is expressed once in AuthorizationHelper and reused everywhere via SpEL (@PreAuthorize).
Fault isolation	If JWT validation fails, the filter clears SecurityContextHolder before delegating to RestAuthenticationEntryPoint, preventing half-authenticated requests.
Statelessness	No HTTP session is created (STATELESS), so every request is independently authenticated.

Logout Request

Notable aspects

Category	Observation
Token revocation	All active tokens of the user are black-listed in a single update statement; no need to track only the two presented tokens.
Idempotence	Calling /logout repeatedly has no side effects after the first call because tokens are already marked as loggedOut=true.
Context clearing	SecurityContextHolder.clearContext() is executed before the 204 is returned to guarantee that thread-locals are clean in pooled servlet threads.

Refresh token Request

Notable aspects

Category	Observation
Validation depth	Both structural checks (signature, expiry) and stateful checks (not black-listed) are performed.
Rotation	Old refresh token is revoked even on success; replay attacks become ineffective.
Expiry symmetry	A single property (jwtProperties.accessTokenExpiration) is the source-of-truth for the expiresIn field sent to the SPA.

Notification

Emission

Notable aspects

Category	Observation
Decoupling	The rest of the system publishes pure domain events without referencing the notification module.
Atomicity	Notification entity is persisted before Web-Socket broadcast; if WS fails, the user still sees the notification after a new / GET / notifications (at refresh for instance)
Asynchrony	The WS push is executed on a dedicated notificationExecutor, so heavy e-mail rendering or SMTP delays cannot slow down the HTTP request that triggered the event.
Scalability	Broker is in-memory (suits one-node deployments). When scaling horizontally, switch to RabbitMQ or a STOMP-capable broker without touching application code.
Template safety	All variables used in the Thymeleaf e-mail are supplied via NotificationContext.asMap(), avoiding template-side service look-ups.
Domain events	Event are genreated per domain e. g. QuoteCreatedEvent, RFQCreatedEvent and publish to ApplicationEvent

Retrieval

Notable aspects

Category	Observation
Data-scope enforcement	Service decides whether the caller is a provider or a stand-alone user purely from AuthInfo; no user-controlled parameters.
Pagination strategy	Returns the last 20 entries sorted by createdAt DESC — simple, index-friendly, no DTO paging state needed on the client.
Consistency	Mark-read updates only the read flag; optimistic locking is unnecessary because the flag is never concurrently set by two users.
Failure modes	Access-denied paths are explicit (AccessDeniedException) and handled by RestAccessDeniedHandler, keeping error JSON uniform.

State Management

Notable Aspects

Category	Observation
Finite-state machines	All RFQ, item and quote flows are driven by explicit state machines (StatusTransitionMatrix<T>), ensuring only legal transitions occur—and making the behavior easy to test and document.
Soft-delete cascade	handleItemSoftDelete() atomically withdraws both item and its quotes, then recalculateForRfq() propagates the new states to the parent RFQ—preserving history while preventing further edits.
Decoupled recalculation	Quote mutations never touch RFQ directly; they simply call recalculateForItem(item). Localized logic keeps writes O(1) and focused, and lets you swap out recalculation without changing core service code.

RFQ

State

Sequence

RFQ Items

State

Sequence

Quote

State

Sequence

Provider Research

Sequence

Notable Aspects

Category	Observation
Specification-builder pattern	Complex provider-search filters (including a Base64→JSON “techSpecs” JSON column) funnel into two simple DTOs (ProviderFilterRequest + TruckFilterRequest) and two builders, avoiding explosion of query parameters or repository methods.