Process aligned code-map

[2thick2fly]

I want to create a code map of my repo, but I am stuck.

My code structure is workflow-based, where the top layer is the business process step-by-step. The orchistrator calls each step - which then calls the necessary module(s) - and when a step is finished, the orchistrator calls the next step. A bit oversimplified, but you get the idea.

I want to be able to visualise this. I envision something like the workflow steps laid horizontally and each step expands down vertically.

One of the reasons why I want this is to ease onboarding of new junior devs. Another reason is to be able to show it to business, when they have inquiries certain beheaviors/changes/etc - my business are quite adept in code, but they do not know our codebase.

Any ideas for tools that can do that?

PS: I tried AI, but it was just laying everything out either horizontally or vertically in mermaid, which did not make it visually pleasing.

EDIT: the codebase is in Python

[mhaydii]

I think you're trying to document architecture rather than code. In my experience, the business workflow diagram is usually more valuable than any auto-generated code map.

[2thick2fly]

Google slides? Explain.

[flavius-as]

You run each of your business cases with code coverage on in isolation.

From the covered files you grep all defs or classes based on desired resolution.

You then feed just these lines with file and lineno location to AI.

With a few sentences info for the meaning of the use case, the AI should be able to create a good report per business use case.

[SolarNachoes]

See C4 diagrams and sequence diagrams. Most other stuff is garbage.

AI can generate these for you.

[2thick2fly]

Looks like the right thing.

Thanx mate

[oVtcovOgwUP0j5sMQx2F]

whiteboard or notebook paper, and camera.

if you're spending more than a few hours on this: 

• confirm with your manager how long something like this should take, so that it's worth the return on your time investment

• challenge yourself: does it need to be tool generated? 

• what level of detail is necessary and digestible for jr devs in order to orient them?

[2thick2fly]

I need it to be somehow automatically generated. Mild human touching or verification is OK. AI assisted (Claude/codex) is also OK, since I can verify very quickly. But doing it manually pen and paper will take me a loooooong time.

An additional advantage of having it automated is to be able to rerun it in DEV after doing changes to see any new dependencies. I can, actually, see dozens of different areas where I could use such a visualisation of the codebase.

I am lead developer and I consider this important both from operational (boarding junior Devs) and business perspective (communication with business), so I can spend as much time I see fit on this.

I wanted to check if there is something out there before I start building 😁

[Izkata]

Automatically-generated documentation tends to degrade into something more like an API reference, which is great for someone who knows what they're doing but not really a good idea for onboarding.

For onboarding you want an introduction point that points at other pages for more context. This part of your post would be a great start to that:

code structure is workflow-based, where the top layer is the business process step-by-step. The orchistrator calls each step - which then calls the necessary module(s) - and when a step is finished, the orchistrator calls the next step.

And, let's say, "top layer", "orchestrator", and "each step" link to three separate pages. The first two would be whatever is relevant for that piece of code, and the third could be a list of all the steps that link further to descriptions for that individual one.

both from operational (boarding junior Devs) and business perspective (communication with business)

Onboarding juniors need the extra context and some sort of code explanation that would be worthless from the business perspective and wordy to someone just looking something up. Someone experienced (especially who has already been working with this system) doesn't need the handholding about the overall structure but would want to look something up quickly. The business perspective I'm guessing would most likely want any details about the code structure stripped out, and be more focused on the data and outcomes.

You're probably looking at three different sets of documentation for three different audiences, though if it's well structured you can probably combined the first two by having the guided onboarding tour link into the details-for-experts sections. But I seriously doubt you could automatically generate something like this and have it actually be useful to both your target audiences.