Sven Ruppert

Client contract from a UI perspective

In this project, the user interface not only serves as a graphical layer on top of the backend, but is also part of the overall contract between the user, the client, and the server. This part focuses on the data flow from the UI’s perspective: how inputs are translated into structured requests, how the client forwards them, and what feedback the user interface processes.

The source code for this version can be found on GitHub at https://github.com/svenruppert/url-shortener/tree/feature/advent-2025-day-03

Here’s the screenshot of the version we’re implementing now.

The basis of the contract is the class ShortenRequest, which was extended in this development step with the new field expiresAt. This field serves as a central repository for expiration dates and is entirely optional – meaning existing clients will continue to function even without this attribute. The UI client is thus both backwards-compatible and future-proof.

public class ShortenRequest {
  private String url;
  private String shortURL;
  private Instant expiresAt;
  public ShortenRequest(String url, String shortURL, Instant expiresAt) {
    this.url = url;
    this.shortURL = shortURL;
    this.expiresAt = expiresAt;
  }
  public Instant getExpiresAt() { return expiresAt; }
  public void setExpiresAt(Instant expiresAt) { this.expiresAt = expiresAt; }
}

The CreateView passes this object to the URLShortenerClient, which handles communication with the server. The decisive factor here is that the user interface does not establish HTTP connections directly but delegates this task to a dedicated client component. This keeps the UI lean and testable, while the client is centrally responsible for logging, error handling and request generation. The central interface is the createCustomMapping method, which maps the extended contract:

public ShortUrlMapping createCustomMapping(String alias, String url, Instant expiredAt) throws IOException {
  logger().info("Create custom mapping alias='{}' url='{}' expiredAt='{}'", alias, url, expiredAt);
  URL shortenUrl = serverBaseAdmin.resolve(PATH_ADMIN_SHORTEN).toURL();
  HttpURLConnection connection = (HttpURLConnection) shortenUrl.openConnection();
  connection.setRequestMethod("POST");
  connection.setDoOutput(true);
  connection.setRequestProperty(CONTENT_TYPE, JSON_CONTENT_TYPE);
  var shortenRequest = new ShortenRequest(url, alias, expiredAt);
  String body = shortenRequest.toJson();
  try (OutputStream os = connection.getOutputStream()) {
    os.write(body.getBytes(UTF_8));
  }
  int status = connection.getResponseCode();
  if (status == 200 || status == 201) {
    try (InputStream is = connection.getInputStream()) {
      String jsonResponse = new String(is.readAllBytes(), UTF_8);
      ShortUrlMapping shortUrlMapping = fromJson(jsonResponse, ShortUrlMapping.class);
      return shortUrlMapping;
    }
  }
  if (status == 409) {
    throw new IllegalArgumentException("Alias already in use");
  }
  throw new IOException("Unexpected status: " + status);
}

This example illustrates how precisely the UI and the client are coordinated. The UI passes a fully populated domain instance (ShortenRequest) that contains all the required fields. The client handles the serialisation, performs the communication, and returns a ShortUrlMapping in response. The UI then displays the relevant data immediately.

A central design principle in this interaction is “data instead of commands”. The UI does not send specific control commands, but always sends complete data objects. The backend decides how to operate based on these objects. This decoupling has several advantages:

1. Extensibility: New fields (e.g. expiresAt) can be added without breaking existing APIs.
2. Traceability: Every operation is fully traceable via the Request object.
3. Security: The client can validate inputs before converting them into HTTP requests.

In the UI, the client’s responses are used to provide feedback and update the current view. Not only is the shortcode displayed, but the entire mapping object is also displayed, which already contains all the values calculated on the server side. The user interface thus always remains in line with the actual system state.

This pattern – a clear contract structure between UI, client and server – creates stability and maintainability in the long term. Changes to the backend API do not require adjustments to the UI logic, as long as the underlying data contract remains unchanged. This establishes a binding communication path that enables technical evolution without impairing user interaction.

Client layer (URLShortenerClient): Extensions

The client layer forms the technical bridge between the user interface and the server. It translates data objects into HTTP requests, monitors the communication, and transfers the results back into domain objects. This chapter shows how the existing class URLShortenerClient has been extended to support the new expiration concept (expiresAt) while ensuring clean, valid communication with the server.

The starting point was the existing function createCustomMapping(String alias, String url), which an overloaded variant has now supplemented. This accepts an additional expiration date (Instant expiredAt) and performs all necessary steps to transfer the data to the server in a complete and compliant manner.

public ShortUrlMapping createCustomMapping(String alias, String url, Instant expiredAt)
    throws IOException {
  logger().info("Create custom mapping alias='{}' url='{}' expiredAt='{}'", alias, url, expiredAt);
  if (alias != null && !alias.isBlank()) {
    var validate = AliasPolicy.validate(alias);
    if (!validate.valid()) {
      var reason = validate.reason();
      throw new IllegalArgumentException(reason.defaultMessage);
    }
  }
  URL shortenUrl = serverBaseAdmin.resolve(PATH_ADMIN_SHORTEN).toURL();
  HttpURLConnection connection = (HttpURLConnection) shortenUrl.openConnection();
  connection.setRequestMethod("POST");
  connection.setDoOutput(true);
  connection.setRequestProperty(CONTENT_TYPE, JSON_CONTENT_TYPE);
  var shortenRequest = new ShortenRequest(url, alias, expiredAt);
  String body = shortenRequest.toJson();
  logger().info("createCustomMapping - body - '{}'", body);
  try (OutputStream os = connection.getOutputStream()) {
    os.write(body.getBytes(UTF_8));
  }
  int status = connection.getResponseCode();
  if (status == 200 || status == 201) {
    try (InputStream is = connection.getInputStream()) {
      String jsonResponse = new String(is.readAllBytes(), UTF_8);
      logger().info("createCustomMapping - jsonResponse - {}", jsonResponse);
      ShortUrlMapping shortUrlMapping = fromJson(jsonResponse, ShortUrlMapping.class);
      logger().info("shortUrlMapping .. {}", shortUrlMapping);
      return shortUrlMapping;
    }
  }

  if (status == 409) 
    throw new IllegalArgumentException("Alias already in use");
  }
  throw new IOException("Unexpected status: " + status);
}

With this method, the extended expiration date is seamlessly integrated into the existing communication flow. The UI calls this method via CreateView, keeping the extension transparent to the user – the new functionality is immediately available without changing the user experience.

In addition to improving the method signature, the consistency of HTTP communication has also been improved. Instead of manually setting headers, the constant JSON_CONTENT_TYPE is now used consistently to avoid format errors and ensure unique typing. This standardisation reduces the risk of inconsistent requests and facilitates later protocol extensions (e.g., for authenticating or signing requests).

Another critical point is logging. The URLShortenerClient logs all relevant steps – from request creation to response processing. This transparency is crucial for understanding the exact process in the event of an error. Especially during the development phase and when integrating new features such as expiresAt, logging provides valuable insights into the timing, format and status of the data transfer.

A typical log snippet might look like this:

INFO Create custom mapping alias='test123' url='https://example.com' expiredAt='2025-12-31T23:59:00Z'

INFO createCustomMapping - body - '{"url": "https://example.com", "alias": "test123", "expiresAt": "2025-12-31T23:59:00Z"}'

INFO createCustomMapping - jsonResponse - '{"shortCode": "ex-9A7", "originalUrl": "https://example.com", "expiresAt": "2025-12-31T23:59:00Z"}'

INFO shortUrlMapping.. ShortUrlMapping[shortCode=ex-9A7, url=https://example.com, expiresAt=2025-12-31T23:59:00Z]

This structured logging follows a clear pattern that makes all the steps involved traceable. It is intended not only for debugging, but also for integration into an audit or monitoring solution in the long term.

In conclusion, it should be noted that the client layer is now fully context-sensitive. It recognises optionally passed expiration dates, validates inputs, communicates clearly structured JSON payloads, and correctly interprets server-side responses. This creates a robust, well-defined interface between the user interface and the backend that can easily accommodate future extensions, such as custom policies or metadata.

Server API and Handler

The server layer forms the backbone of the entire architecture. It receives requests, interprets the data structures, and coordinates the creation, storage, or deletion of short links. With the introduction of the expiration date (expiresAt), the API has been extended by a significant semantic dimension. The goal was to integrate this new information into the existing request-response flow without causing compatibility issues with older clients.

The central point of contact for incoming POST requests to create a short link is the ShortenHandler. This handles the JSON payload, performs validations, and interacts with the UrlMappingStore. In doing so, the processing has been extended to correctly extract the expiration date from the JSON object and pass it to persistence.

final String body = readBody(ex.getRequestBody());
ShortenRequest req = fromJson(body, ShortenRequest.class);
if (isNullOrBlank(req.getUrl())) {
  writeJson(ex, BAD_REQUEST, "Missing 'url'");
  return;
}
final Result<ShortUrlMapping> urlMappingResult =
    store.createMapping(req.getShortURL(), req.getUrl(), req.getExpiresAt());
urlMappingResult
  .ifPresentOrElse(success -> logger().info("mapping created success {}", success.toString()),
                   failed -> logger().info("mapping created failed - {}", failed));
urlMappingResult
  .ifSuccess(mapping -> {
    final Headers h = ex.getResponseHeaders();
    h.add("Location", "/r/" + mapping.shortCode());
    writeJson(ex, fromCode(201), toJson(mapping));
  })
  .ifFailure(errorJson -> {
    try {
      var parsed = JsonUtils.parseJson(errorJson);
      var errorCode = Integer.parseInt(parsed.get("code"));
      var message = parsed.get("message");
      writeJson(ex, fromCode(errorCode), message);
    } catch (Exception e) {
      writeJson(ex, CONFLICT, errorJson);
    }
  });

The ShortenHandler deliberately does not use a framework, but works with native Java APIs (HttpExchange, HttpURLConnection) to keep the control flow completely transparent. This decision is not only for traceability but also enables a precise understanding of how HTTP works at the lowest level. The code clearly shows the steps of the server cycle: read body, deserialise, validate, invoke domain logic, and write response.

Another example is the ListHandler, which has been slightly modified to take advantage of the modern Sequenced API (List.getFirst()), thus increasing readability:

private static String first(Map<String, List<String>> q, String key) {
  var v = q.get(key);
  return (v == null || v.isEmpty()) ? null : v.getFirst();
}

Special attention is paid to robust JSON data processing. Here, it has been ensured that line breaks and escape sequences do not cause parsing problems. In the JsonUtils module,  a cleanup step was introduced before parsing:

s = s.replaceAll(“\\n”, “”);

This prevents multi-line JSON data from leading to errors – a typical stumbling block for APIs that process manually generated or logged payloads.

Overall, the server API deliberately remains flat and declarative. Each operation represents a clearly defined domain action; there is no excessive branching or hidden state change. By adding expiresAt, this style is retained, and the system continues to react deterministically: A request creates a mapping, optionally with an expiration date, and returns the complete record as JSON.

This simplicity is not a coincidence, but an expression of a design principle that runs through all levels of the application: explicit data flows instead of implicit magic. The result is a system that remains understandable for both users and developers and can be reliably expanded.

Persistence and Store Implementations

The persistence layer is the foundation on which the entire system’s reliability rests. With the introduction of the expiration date (expiresAt), it had to be expanded accordingly so that this new information can be reliably stored, queried and evaluated – regardless of whether the data is stored in memory or in a persistent database such as EclipseStore.

At the center of this layer is the UrlMappingUpdater interface, which has been extended by a new method. This method adds the Instant expiredAt parameter to the previous signatures, so that the persistence layer can now explicitly handle expiration times.

public interface UrlMappingUpdater {
  Result<ShortUrlMapping> createMapping(String originalUrl);
  Result<ShortUrlMapping> createMapping(String alias, String url);
  Result<ShortUrlMapping> createMapping(String alias, String url, Instant expiredAt);
  boolean delete(String shortCode);
}

This clearly states that every implementation must process flow information. This adaptation follows the principle of contract-based design – the interface defines which capabilities the specific implementation must possess without prescribing their technical details.

InMemory Implementation

The first customization was done in the InMemoryUrlMappingStore. This class is primarily used for tests and volatile runtime environments and stores all mappings in a ConcurrentHashMap. By extending the createMapping methods, expiration data is now correctly transferred to the MappingCreator.

@Override
public Result<ShortUrlMapping> createMapping(String alias, String originalUrl, Instant expiredAt) {
  logger().info("alias: {} - originalUrl: {} - expiredAt: {} ", alias, originalUrl, expiredAt);
  return creator.create(alias, originalUrl, expiredAt);
}

In  the MappingCreator itself, the expiration time is integrated into the ShortUrlMapping and stored directly when created:

public Result<ShortUrlMapping> create(String alias, String url, Instant expiredAt) {
  logger().info("createMapping - alias='{}' / url='{}' / expiredAt='{}'", alias, url, expiredAt);
  final String shortCode;
  if (!isNullOrBlank(alias)) {
    if (repository.containsKey(alias)) {
      return Result.failure("Alias already exists");
    }
    shortCode = alias;
  } else {
    shortCode = generator.generate();
  }
  var mapping = new ShortUrlMapping(shortCode, url, Instant.now(clock), Optional.ofNullable(expiredAt));
  store.accept(mapping);
  return Result.success(mapping);
}

This pattern shows that expiration information, if any, is directly part of the ShortUrlMapping domain object. The code is deliberately simple: no additional state, no special treatment, but only an optional value.

EclipseStore Implementation

The EclipseStoreUrlMappingStore has also been adapted for permanent storage. The same principle applies here, but with a focus on long-term persistence.

@Override
public Result<ShortUrlMapping> createMapping(String alias, String originalUrl, Instant expiredAt) {
  logger().info("alias: {} - originalUrl: {} - expiredAt: {}", alias, originalUrl, expiredAt);
  return creator.create(alias, originalUrl, expiredAt);
}

Tightly coupling with the same MappingCreator ensures complete consistency in behaviour between the InMemory and EclipseStore variants. The only difference is the storage duration: While the data in the InMemory store is lost on restart, it remains persistent in the EclipseStore.

Uniformity and Compatibility

A central goal of these adaptations was the complete equal treatment of all persistent species. Whether it’s testing, development mode, or production, all paths use the same objects and methods. This eliminates the risk of divergent logic across different storage types. Changes to the domain, such as the introduction of expiresAt, therefore only have to be implemented in one place.

Advantages of the approach

This consistent standardization brings several advantages:

1. Transparency: Every mapping operation is traceable and documented in the log.
2. Consistency: InMemory and EclipseStore stores behave identically.
3. Extensibility: New storage mechanisms (e.g., SQL, key-value store, cloud) can be easily added as long as they fulfil the interface contract.

With this extension, the persistence layer becomes the system’s reliable backbone. The expiration date is now a full-fledged part of the data model – precisely recorded, securely stored and retrievable at any time. This means that future functions such as automatic cleaning of expired entries or time-based statistics can be implemented directly on this basis.

Domain Model and Defaults

The class ShortenRequest has been extended to include the field expiresAt. This field allows you to pass an optional expiration time, which is set by the user in the UI and delivered to the server as an instant in JSON format. This information thus becomes a full-fledged component of the data model and can be further processed at both the transport layer and the persistence layer.

public class ShortenRequest {
  private String url;
  private String shortURL;
  private Instant expiresAt;
  public ShortenRequest(String url, String shortURL, Instant expiresAt) {
    this.url = url;
    this.shortURL = shortURL;
    this.expiresAt = expiresAt;
  }
  public Instant getExpiresAt() { return expiresAt; }
  public void setExpiresAt(Instant expiresAt) { this.expiresAt = expiresAt; }
  public String toJson() {
    var a = shortURL == null ? "\"null\"" : "\"" + JsonUtils.escape(shortURL) + "\"";
    var b = expiresAt == null ? "\"null\"" : "\"" + JsonUtils.escape(expiresAt.toString()) + "\"";
    return """
        {
          \"url\": \"%s\",
          \"alias\": %s,
          \"expiresAt\": %s
        }
        """.formatted(JsonUtils.escape(url), a, b);
  }
}

It is important to note that the expiresAt value is not mandatory. This keeps existing clients, and server calls compatible, even if they don’t set the field. The domain model was deliberately designed to remain backwards-compatible and extensible, an essential principle when introducing new features.

ShortUrlMapping as a central link

The ShortUrlMapping class represents the central data element between the client and the server. It contains all the relevant information of a short link: the generated shortcode, the destination URL, the creation date and, optionally, the expiration date. By using Optional<Instant>, the possible absence of an expiration date is explicitly modelled.

public record ShortUrlMapping(String shortCode, String originalUrl, Instant createdAt, Optional<Instant> expiresAt) { }

This decision underscores the model’s functional properties: an immutable data element that is fully defined only when it is created. Changes to a mapping are always made through new creations or explicit updates – never through silent mutations.

DefaultValues – Central System Constants

In addition to the model classes, the DefaultValues class has also been extended. It contains constants that are used throughout the application, especially the base URL for generated short links.

public final class DefaultValues {
  TODO - must be editable by user
  public static final String SHORTCODE_BASE_URL = "https://3g3.eu/";
  public static final int ADMIN_SERVER_PORT = 9090;
  public static final String ADMIN_SERVER_HOST = "localhost";
  public static final String ADMIN_SERVER_PROTOCOL = "http";
  more path definitions ...
}

The constant SHORTCODE_BASE_URL serves as the basic component for generating and displaying short links in the user interface. Although it is currently statically defined, it has already been noted that it will be dynamically configurable in a future iteration. This lays the foundation for flexible deployment scenarios in which different environments (e.g., development, test, production) can use their own base URLs.

AliasPolicy with Logging

Another component of the domain model is the AliasPolicy, which defines rules for valid aliases. Logging has been added as part of the enhancements to make the validation processes easier to understand:

public final class AliasPolicy implements HasLogger {
  public static Validation validate(String alias) {
    HasLogger.staticLogger().info("validate - {}", alias);
    if (alias == null || alias.isBlank()) return Validation.fail(Reason.NULL_OR_BLANK);
    if (alias.length() < MIN) return Validation.fail(Reason.TOO_SHORT);
    if (alias.length() > MAX) return Validation.fail(Reason.TOO_LONG);
    if (! ALLOWED_PATTERN.matcher(alias).matches()) return Validation.fail(Reason.INVALID_CHARS);
    return Validation.success();
  }
}

This logging makes faulty aliases immediately visible, making troubleshooting the interaction between the UI and the backend much easier.

With these adjustments, the domain model becomes a robust, clearly structured core of the application. The central entity ShortUrlMapping fully reflects the real-world state of a shortlink, while ShortenRequest controls the creation of new entries and provides system-wide constants to DefaultValues. All extensions remain consistent with the original design principle: simple, functional structures that precisely define what a user can create, modify, or retrieve.

JSON serialisation and deserialization

The reliability of communication between the components of an application depends crucially on the quality of the serialisation layer. This chapter describes how JSON processing has been extended and stabilised to safely transport the new expiresAt field while improving code readability and error tolerance.

Extending Serialisation in JsonUtils

The JsonUtils class  forms the backbone of JSON processing in the project. It provides both generic helper methods and specific serialisation routines for the most critical domain objects. With the introduction of the expiration date, it was necessary to ensure this field was correctly integrated into JSON documents without affecting legacy data formats.

In the method for serialising ShortenRequest, the field expiresAt has therefore been  added:

if (dto instanceof ShortenRequest req) {
  Map<String, Object> m = new LinkedHashMap<>();
  m.put("url", req.getUrl());
  m.put("alias", req.getShortURL());
  m.put("expiresAt", req.getExpiresAt());
  return toJson(m);
}

This change will automatically include the expiration date, if it exists. If it is not set, the field appears as null in the JSON  and thus remains syntactically valid. This explicit representation of null values improves readability and allows the server to clearly distinguish between “not set” and “deliberately empty”.

Extending Deserialization

Analogous to serialisation, deserialization has also been extended to read expiresAt from JSON data correctly. In the fromJson method, the customisation is done:

if (type == ShortenRequest.class) {
  String url = m.get("url");
  String alias = m.get("alias");
  Instant expiresAt = parseInstantSafe(m.get("expiresAt"));
  return (T) new ShortenRequest(url, alias, expiresAt);
}

The parseInstantSafe function converts an ISO-8601 string to an instant object and handles invalid or empty values gracefully. This error resistance is significant for clients that may send different or older JSON structures.

Purge of incoming JSON data

A common problem with APIs is reading in JSON data that contains unintentional line breaks or extra escape characters. To prevent parsing errors,  simple preprocessing has been introduced in JsonUtils.parseJson:

s = s.replaceAll(“\\n”, “”);

This step removes all line breaks before the parser runs. This reliably recognises and correctly interprets both manually formatted JSON files and logged messages. This customisation makes the system more robust against inconsistent formatting that is common in real-world environments. (At this point, however, I am aware that it is far from sufficient…)

Optimisation of JSON output

As part of these changes, the toJsonListing method has also been revised. Instead of a complicated StringBuilder structure, a simple, readable string concatenation is now used:

return "{" +
    "\"mode\":\"" + escape(mode) + "\"," +
    "\"count\":" + count + "," +
    "\"items\":" + toJsonArrayOfObjects(items) +
    "}";

This simplification reduces the susceptibility to errors and makes debugging easier. Especially in systems that do not require frameworks, code readability is a decisive factor for maintainability and error diagnosis.

Consistency and interoperability

An essential aspect of the revision of serialisation was maintaining interoperability across different clients and API versions. Since all fields are still serialised on a string-by-string basis and the JSON structure is explicit, the data exchange remains fully compatible even with older clients. This means that a client that does not send expiresAt will be accepted by the server, and a server that does not expect the field will ignore it.

This loose coupling between transmitter and receiver is a central design goal of the project. It allows incremental expansions without updating all components at once.

The revision to JSON processing strengthens the application’s robustness and future-proofing. By specifically extending JsonUtils to include the expiresAt field, cleaning incoming data, and simplifying the output, serialisation is now both technically stable and semantically precise. It thus meets the requirements of a modern, evolvable interface that remains clearly comprehensible for both automated processes and human readers.

Security and robustness in the UI flow

As the complexity of the user interface grows, so does the responsibility to ensure that all interactions remain predictable, valid, and stable. This chapter explains how security considerations and robustness were built directly into the UI flow – from input validation to defensive navigation decisions to dealing with external browser APIs.

Input validations in the generation dialogue

The most important security aspect in the UI is validating user input. As soon as a new short link is created, the application checks whether the entered URL contains a valid scheme. This prevents potential attacks by manipulated or unsupported protocols at an early stage.

binder.forField(urlField)
    .asRequired("URL must not be empty")
    .withValidator(url -> url.startsWith("http://") || url.startsWith("https://"),
                   "Only HTTP(S) URLs allowed")
    .bind(ShortenRequest::getUrl, ShortenRequest::setUrl);

This simple validation only accepts URLs that can be reached via secure or well-defined transport protocols. This protects both the user and the application from unwanted interactions with unsafe targets. However, it is not yet full input validation.

Another part of the validation concerns the expiration date. Here, it is ensured that a selected point in time is always in the future:

if (exp.isPresent() && exp.get().isBefore(Instant.now())) {
  Notification.show("Expiry must be in the future");
  return false;
}

This mechanism protects against incorrect entries and inconsistent data states, especially when users edit the form multiple times or select times that have already expired.

Defensive navigation in the detail dialogue

The detail dialogue (DetailsDialog) also follows the principle of secure interaction. If a saved URL is opened via the “Open” button, this is done exclusively by calling the method UI.getCurrent().getPage().open(), but only if the destination is clearly recognised as an HTTP or HTTPS link. This prevents internal or local resources from being accidentally or intentionally called via the UI.

openBtn.addClickListener(_ -> {
  if (originalUrl.startsWith("http://") || originalUrl.startsWith("https://")) {
    fireEvent(new OpenEvent(this, shortCode, originalUrl));
    getUI().ifPresent(ui -> ui.getPage().open(originalUrl, "_blank"));
  } else {
    Notification.show("Invalid URL scheme");
  }
});

This decision strengthens the separation between internal and external resources. User actions are controlled to prevent unwanted side effects outside the application.

Dealing with the Clipboard API

Another security-relevant topic is how to use the native Clipboard API. For data protection reasons, this is only available in secure browser contexts, i.e. via HTTPS or localhost. The application uses this API to copy shortcodes and URLs to the clipboard conveniently. If access is not allowed in the current context, the call does not result in an error, but is silently discarded – an example of defensive programming behaviour in the UI.

UI.getCurrent().getPage().executeJs(“navigator.clipboard.writeText($0)”, SHORTCODE_BASE_URL + m.shortCode());

This non-blocking call avoids JavaScript errors and keeps the UI stable even if the browser rejects the action. The application always responds in a controlled manner and remains in a valid state.

Consistent feedback and fault tolerance

A core element of robustness is the feedback system. Every user command – whether successful or incorrect – triggers visual feedback. The application consistently uses the Vaadin notification component for this purpose. It provides information about validation errors, successful copying operations and system messages without interrupting the workflow. This asynchronous reporting system supports the idea that a user can continue at any time, even if a single operation fails.

Notification.show(“Alias already assigned or error saving”, 3000, Notification.Position.MIDDLE);

This type of error communication avoids frustration and contributes to perceived stability. The user remains informed, but never blocked.

The measures described in this chapter – input validations, defensive navigation, and safe clipboard use – share a common goal: robustness through caution. Every action in the user interface is checked, every external interface is secured, and every user interaction is clearly reported. This allows the UI to achieve a high level of error tolerance without sacrificing ease of use. This balance of security and user-friendliness concludes the technical implementation of the detailed dialogue. It lays the foundation for the upcoming enhancements, in which security and user experience will continue to go hand in hand.

Result

With today’s Advent calendar, the application has reached a decisive degree of maturity. While the first parts mainly laid the structural and functional foundations, today it is all about the depth of detail and the quality of interaction. The focus was on transitioning from a technically functional interface to a well-thought-out, user-centric application.

The newly introduced detail dialogue marks a central turning point: it allows viewing individual entries in context without leaving the overview. This concept combines technical clarity with ease of use, creating a modular structure that can easily accommodate future expansions. By using events to decouple the components, the architecture remains clean, traceable and testable.

The integration of the expiration date is also proving to be a milestone in the system’s functional development. From input in the UI to the client layer to persistence and JSON processing, the new parameter has been consistently integrated into all layers. The original design was deliberately kept simple – each layer knows only its own responsibility, and none contains logic that anticipates another layer. The result is a consistent, precise data flow that combines technical precision with semantic transparency.

Another critical advance is improving the user experience (UX). Consistent interaction patterns, precise feedback, and security-conscious behaviour make the application both intuitive and trustworthy. The combination of immediate feedback, non-blocking error handling, and a harmonious visual-functional design shows how technological rigour and user focus can go hand in hand.

From an architectural point of view, this part of the Advent calendar illustrates that even in small projects, cleanliness, coherence, and expandability are the key success factors. The clear separation between UI, client, server, and persistence not only enables efficient maintenance but also opens the way for future modules – such as administrative views, bulk operations, or security policies for user groups.

Cheers Sven