Three Letter Abbreviations (TLA) Sample Application

This sample application aims to illustrate how to ...

• ... validate a Domain-driven Design (DDD) model implementation (tactic, code) against a Context Mapper model using our ArchUnit extension.
• ... use generated diagrams of Context Mapper inside your documentation (in this case the arc42 document).
• ... implement an application using tactic DDD patterns and Onion Architecture (just an example; we are not claiming that this is "the way" at all).

The idea of the application is to provide a RESTful HTTP API that allows users to lookup meanings of Three Letter Abbreviations (TLAs)¹. The credit for the domain idea goes to socadk! Thanks!

The main features are:

• Resolve TLAs with their meanings.
• Propose new TLAs.
• Proposed TLAs are reviewed and accepted or rejected.
• TLAs can be archived.

Note: The example is a work in progress and not complete at all.

The application is implemented using the following technology:

• Java 17
• Spring Boot
• Open API generator (to generate the controllers and DTOs)
• jMolecules DDD annotations
• H2 in-memory database (to store the TLAs)
  • Flyway for database migration

Start exploring the example application in the Gitpod online IDE right now:

Getting Started

You can clone and then build the application with the following Maven command:

./mvnw clean package

To run the application from the command line, use the following command:

./mvnw spring-boot:run

Preconditions:

• Java installed (we use JDK 17)
• Graphviz (dot) installed (because we generate Context Maps)

To run the application within your chosen IDE, run the main method in the org.contextmapper.sample.tlas.infrastructure.application.TlaApplication class.

API-First

We follow the API-first approach and generate the controllers and DTOs out of an Open API specification.

The API specification can be found here. (src/main/resources/tla-web-api.yml)

Note: Run the Maven build at least once before you import the project into your IDE (Open API generator needs to generate the controllers and DTOs). You can find the generated sources (Open API) under target/generated-sources/openapi/src/main/java.

TBD (future work): From CML we can also generate MDSL and then from MDSL an Open API specification. In the future we could show how to automate this here (CML -> MDSL -> Open API -> Code). However, under src/main/resources/mdsl we have already written the MDSL example that allows us to generate the Open API specification. To adjust the API via MDSL we currently have to generate and replace src/main/resources/tla-web-api.yml manually.

Endpoints

Currently, there are two endpoints implemented. One to get all TLAs and another one to get a single TLA by name.

Get all TLAs

curl  http://localhost:8080/api/v1/tlas

[
   {
      "name":"TLA",
      "meaning":"Three Letter Abbreviation",
      "alternativeMeanings":[
         "Three Letter Acronym"
      ]
   },
   {
      "name":"ADR",
      "meaning":"Architectural Decision Record",
      "alternativeMeanings":[]
   },
   {
      "name":"ASR",
      "meaning":"Architecturally Significant Requirement",
      "alternativeMeanings":[]
   },
   {
      "name":"CSC",
      "meaning":"Client/Server Cut",
      "alternativeMeanings":[]
   }
]

Get single TLA by Name (ID)

curl  http://localhost:8080/api/v1/tlas/ADR

{
   "name":"ADR",
   "meaning":"Architectural Decision Record",
   "alternativeMeanings":[]
}

Architecture

In this sample application we implement/demonstrate tactic Domain-Driven Design (DDD) together with Onion Architecure. With an ArchUnit Test we ensure that our code complies with this architectural style and its rings (domain, domain services, application services, infrastructure).

If you are not familiar with onion architecture, I recommend the following slides/posts by cstettler: (unfortunately in GERMAN only; but the visualizations are nice/helpful anyway)

• DDD mit Onion Architecture & Stereotypes (Slides)
• DDD mit Onion Architecture (Blogpost)

Note: To stick with the architectural style and its circular shape, we talk about rings and not layers (AD1: Layering Scheme - Onion Architecture).

Markdown Any Decision Records (MADR)

We use MADRs to document our architectural decisions. You can find them here (docs/madr).

arc42 Documentation

With this sample app we demonstrate how you can use generated diagrams by Context Mapper in your documentation. This repo contains an arc42 document written in AsciiDoc. The Maven build automatically generates the documentation as a PDF and in HTML.

The GitHub Actions workflow automatically deploys the documentation as a GitHub page. You can find the deployed documentation here: TLA Sample App - Architecture (arc42)

Contributing

Contribution is always welcome! Here are some ways how you can contribute:

• Create Github issues if you find bugs or just want to give suggestions for improvements.
• This is an open source project: if you want to code, create pull requests from forks of this repository. Please refer to a Github issue if you contribute this way. In our wiki you can find out how to build the project and setup the development environment locally.
• If you want to contribute to our documentation and user guides on our website https://contextmapper.org/, create pull requests from forks of the corresponding page repo https://github.com/ContextMapper/contextmapper.github.io or create issues there.

Licence

Context Mapper is released under the Apache License, Version 2.0.

Footnotes

1. TLA: "Three Letter Abbreviation" or also "Three Letter Acronym". ↩