Surprising Architecture

Hi,

“RCoffee [an internal tool for content production] accesses the test servers via SSH and displays the Tomcat logs”

Wow. That was surprising.

I have been working with this client for a year now.

The application is the market leader in its field, and the current version was developed over 10 years ago.

A lot has accumulated, of course. And when I am hired, the technical debt is usually very large.

But after a year on the project, I didn’t think I could still be surprised.

The content creators use an internally developed tool to create content. To allow the content creators to check if their changes lead to errors in the application, the logs are displayed in the tool. Via SSH.

And every content creator has their own SSH key.

Uff.

Alright then. Digest it first - and then make sure that others find out about it sooner than I did in the future.

That’s where architecture documentation (with images) is perfect. A year ago, I started catching up on this architecture documentation with arc42, primarily with the goal of fully understanding the system. Today, this documentation is so helpful that all new employees are trained using it. The training time has been reduced from a quarter of a year to less than two weeks. Internally, we call this the famous “pressure fueling.”

So, if there’s an arrow in this documentation pointing from the tool to the backend labeled “SSH to read logs,” it automatically becomes a topic.

What can you learn from this?

A legacy system will always have surprises. That’s not a bad thing. Look ahead and make sure that at least the next person is not surprised by it.

Rule the Backend,

~ Marcus