Skip to content

Domain-driven Design (DDD) & Context Mapper: Three Letter Abbreviations (TLAs) Sample Application

License

Notifications You must be signed in to change notification settings

ContextMapper/ddd-cm-tla-sample-application

Repository files navigation

Context Mapper

Three Letter Abbreviations (TLA) Sample Application

master build codecov Gitpod ready-to-code License

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)1. 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:

Push

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)

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:

Licence

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

Footnotes

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

About

Domain-driven Design (DDD) & Context Mapper: Three Letter Abbreviations (TLAs) Sample Application

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project