This is one of the backend services that push data to the documentation repository.
The build of this service includes tests that generates various JSON file for the central documentation repository.
The principle is relatively straightforward: gather data during testing / building and combine this data in a Gradle task to get a unified description of an application’s component.
The application’s main description is explicitly defined in a test, allowing for the generation of all hard-coded descriptions from one place: ArchitectureDocumentationTests
The dependencies of this application are generated by the tests of the classes that serve as proxies for these dependencies. For example, BackendService2ClientTests for BackendService2Client, or AuditLogRepositoryTests for AuditLogRepository. Additionally, tests for HTTP-based dependencies gather information about the endpoints called from the WireMock interactions.
The dependents of this application are generated from PACT contracts, as seen in ContractTests. Their descriptions are derived based on the contract’s consumer name. This mapping process will throw an exception if there is no description available for a new consumer. Failing the test in cases of "unmapped" consumers ensures the list of dependents is accurate and less prone to errors.
For those not utilizing PACT, dependents can be manually specified, akin to the method used for describing the application.
All collected data is stored in JSON format within the build/architecture-documentation folder.
During the CI-build of the master branch, the generated files are collected, and processed using a shared GitHub action of the central documentation repository.
This allows us to change anything we want regarding the handling / combination of the data without having to update all relevant component repositories.
The only changes that need to be synchronized with the component repositories are changes to the data models.
As of now, this is just the beginning. There are several possible sources of data, to make the generated application description more dynamic and complete:
-
We could involve parts of the application configuration to enrich the data about 3rd party systems (e.g. hostnames).
-
For databases, we could include the type of SQL database based on the used JDBC driver.
-
For databases, we could determine and include the description of tables, columns, indices and other relevant parts.
-
For NoSQL databases, we could detect which ones are used based on dependencies and configuration properties.
-
For messaging, we could include the used topics / queue names as well as routing keys.
We also need mechanisms to make it harder to accidentally NOT document something that should be documented.