Interface/ Interoperability documentation

[DaveC0der]

Hello everyone,

I would like to create an architecture documentation that primarily visualizes the interoperability between interconnected software systems and links it with host and interface profiles.

In addition, I would like to represent the following contents via AsciiDoc: Context, Software Architecture, Constraints, Infrastructure Architecture and Decision Log (according to the Software Guidebook or arc42).

What would be a good solution to realize this in a Single Source of Truth model (sources stored in Bitbucket/Git) and represent it in a convenient way?

At first, I thought of a pipeline with docToolchain and arc42, but is this also possible with Structurizr tools?
How could host profiles and interface profiles be best integrated and linked with the diagrams?

For example:
MFT A -----> MFT B

MFT A: gets an individual host profile in AsciiDoc format

MFT B: gets an individual host profile in AsciiDoc format

The edge A→B: gets an interface profile

I am looking for a clean and simple overall solution to document this clearly and purposefully, ideally using only docs-as-code tools and a central repository.

was thinking of this principle (see attachment), but with GitHub serving as the central repository (the single source of truth) for the Software Guidebook/arc42 chapters as well as the interface profiles, and Confluence acting as the target platform. Does that make sense for you?

Perhaps someone has experience, suggestions, and/or ideas for this?

Many thanks in advance for your help!

Best regards
Dave

[simonbrowndotje]

... and Confluence acting as the target platform

I'd stick with docToolChain if your goal is to target Confluence - this isn't something that's supported by the Structurizr tooling.

[DaveC0der]

Thanks for your reply. Yes, in the context of exporting to Confluence, that makes sense. But could doctoolchain be integrated with Structurizr to visualize interfaces between systems? Is there a way to elegantly link elements in Structurizr with interface fact sheets in AsciiDoc or table format? For example, I am thinking of a clickable diagram as an SVG. In my documentation, the focus is very much on interoperability. Does you or anyone have a practical idea for this?

[simonbrowndotje]

Does you or anyone have a practical idea for this?

I don't ... I'd recommend opening a discussion on the docToolChain repo, since this already integrates Structurizr.