View on GitHub


Architectural Decisions Records embedded in Java code

Embedded Architectural Decision Records

Build Status Maven Central Javadocs License

Architectural knowledge captured in architectural designs and architectural decisions is primarily created and consumed in tools made for software architects. Developers, also consuming and creating architectural knowledge, do not always use such tools; this adds to the gap between these two roles often observed in practice. Architectural erosion and knowledge vaporization are two of the consequences.

With this repository, we show how to narrow the gap with architecture domain-specific Java annotations. These annotations allow developers to reference and create architectural decision knowledge directly in code. This knowledge can then automatically be processed by other tools to provide additional integration and collaboration capabilities.

Currently, following architectural decision records are supported:

See for more information on architectural decision records.


Example for complete embedding

@MADR(value = 1,
    title = "Implement entire business logic layer as POJO",
    contextAndProblem = "Need to select a single consistent ComponentImplementationParadigm' for entire business logic layer",
    alternatives = {"POJO", "JEE EJB", "Spring Bean"},
    chosenAlternative = "POJO",
    justification = "Because it is a company-wide policy, see",
    relatedDecisions = {2, 3})
public class MADRAnnotationDemoClass {
    public int sampleBusinessLogic(String input) {
        return 42;

@MADR indicates that the annotation used the format defined by the “Markdown Architectural Decision Record”. The content is directly embedded in the annotation.

Example for a linked ADR

public class MADRAnnotationDemoClass {
    public int sampleBusinessLogic(String input) {
        return 42;

By using @ADR(1), the annotation points to ADR 0001. The convetion is that the decisions are stored in docs/adr/ with a running number. They can be of an arbirary format, such as MADR or Michael Nygard’s format, which is supported by adr-tools. Example MADRs can be seen at the ADR log of the adr-log tool.

Use in your projects


compile 'io.github.adr:e-adr:1.0.0'



Development information

gradlew assemble requires the upload to maven central configured properly. Thus, please use gradlew jar to generate the jar.