/The-Perfect-Greenfield

Primary LanguageHTML

Gitpod ready-to-code Documentation Read Now

The-Perfect-Greenfield

About this repository

This repository showcases the initial steps needed to set up the perfect greenfield project, i.e. a system that is:

  • architecturally well-thought-out, based on the real requirements
  • clearly documented, i.e. documentation is easy to consume and produce and provides all necessary information to architects and developers
  • explicit in the implementation of architectural concepts
  • automatically validated in the conformance of implementation to documentation

With that, it tackles the most common issues of hard-to-maintain, if not even non-existing, documentation as well as having documentation and implementation aligned.

So how do I implement the Perfect Greenfield?

The repository follows a reality-proven approach with 4 steps, each consisting of different methods and tools.

  1. Designing the Functional Architecture
  2. Designing the Technical Architecture
    • Understand the technical requirements by identifying quality qoals
    • Design the technical view on different abstraction levels and identify main concepts of the architecture
    • Approaches: Definition and priorization of Quality Goals using ISO 25010, Design of technical architecture
    • Tools: C4-Model for PlantUML
  3. Communicating the Designed Architecture
    • Document the functional and technical architecture as well as the reasons that led to them using the prviously designed artifacts
    • Define implementation guidelines for developers to have a consistent and architecture-explicit code base
    • Approaches: Arc42, Architecture Decision Records, Architecture-explicit Code
    • Tools: Any AsciiDoc Editor, jMolecules with ByteBuddy Integration
  4. Validating the Implementation of the Architecture
    • Make the documentation validate the implementation in an automated fashion
    • Generate documentation based on the actual implementation, e.g. runtime views and overviews of architecture violations
    • Approaches: Living Documentation
    • Tools: jQAssistant with integration for jMolecules, ContextMapper, and Spring

Using this repository

This repository was created so that each single step in designing and implementing the perfect greenfield can be followed using the commit history.

$ git log --pretty=oneline --abbrev-commit
91b1433 (HEAD -> main, origin/main, origin/HEAD) Added Plantuml Reporting for Event Flow
3937eb2 Implementation of the Update Training Time use case
3f56db1 Implemented ADR for Bounded Context implementation
f9c919b Added ADR for Bounded Context implementation
2d3025b Implemented ADR for Usage of jQAssistant
62abbad Added ADR for Usage of jQAssistant
cb35c4e Implemented ADR for Usage of jMolecules
59c96d1 Added ADR for Usage of jMolecules
0a72884 Basic Maven Project Setup
210393f Added ADR overview and template
d2141d6 Updated Arc42 with available information
d70df01 Added Arc42 template
7a864db Added C4 Model Diagrams
38668e2 Added High-level Context Map
b3f179c Added Domain Stories
0e584f4 Added gitpod configuration
25bb45c Initial commit

You can use the project either using GitPod.io (see Badge in the beginning of this readme) or locally after cloning this repository.

Afterwards, simply run a mvn clean install (JDK 11 required).

Under target\jqassistant\report\asciidoc\ you'll have the resulting documentation. This is also linked in the beginning of this readme.