Architecture Documentation & Dev Branch Onboarding Guide

[FedericoMusa]

Hi everyone,

I’m Federico, an Technical Specialist with extensive experience in industrial processes (Oil & Gas) and a software developer. I’ve been diving into the dev branch of PyModbus to contribute to the architecture documentation, as requested in the README.

The Problem: While setting up the environment, I noticed significant friction for new contributors. The current refactoring in the dev branch has moved core logic (like the old factory) into a more modular structure, but the onboarding examples and pathing are currently breaking for new local setups.

My Proposal: I want to contribute two specific documents to reduce this technical debt:

Onboarding Master Context: A clear guide on how to link the library locally (pip install -e .) and orchestrate the async server/client examples in the current branch state.

Decoder Architecture Map: A technical breakdown of pymodbus/pdu/decoders.py, explaining how the DecodePDU class acts as the 'dispatcher' for industrial frames.

My goal is to help industrial users and developers understand the 'why' behind the current modularity, ensuring the project remains auditable and easy to scale.

I’d love to get your green light to start drafting these in a Pull Request.

Best regards, Federico.

[janiversen]

what do you mean by onboarding examples ? as far as I know all the examples work, if not that is a serious bug.

More architectural documentation is very welcome, but lets ensure it is started on the right foot, so lets solve your example problems first.

can I please ask you to file one or more issues with what is not working and as much documentation as possible so we can solve it.

[FedericoMusa]

Hi Jan,
Thank you for your response and for the clarification. I truly value your time and dedication to the project.
It is very likely that the friction I encountered is related to my local environment configuration or pathing, rather than a bug in the logic—I remain open to the possibility that I might have missed a specific step in the setup.
My proposal to add documentation arose precisely from this experience: I faced some roadblocks while trying to run the examples in the current dev branch state and my only goal was to help future contributors navigate that same path more easily.
As you suggested, I will take the next 24 hours to perform a clean-slate test and prepare a detailed report with my environment specs and findings.
Best regards,
Federico.

[FedericoMusa]

Hi @janiversen,

Following your request, I performed a "clean slate" test on the dev branch to pinpoint exactly where the onboarding process breaks for new contributors.

I have attached a Technical Report (PDF) documenting the findings. It covers:

The step-by-step reproduction of the issue.

The root cause analysis (related to modular pathing vs. editable installs).

A proposed fix for the README and the error messages.

(Please note that I am not a native English speaker, so I apologize in advance for any awkward phrasing in the document).

I hope this provides the documentation you needed. I am ready to submit a PR with these changes if you find the analysis correct.

Best regards, Federico
executive _summary.pdf

[janiversen]

Seems you did not read the error message in step 2. you need to be in the examples directory when running most of the examples.

Your proposed update for README is not correct, you want a development environment so "pip install -e ." is mot sufficient.

Your proposed change to the error message is not correct, the problem is that most examples uses helper.py located in the examples directory. The error provides a url link, that explains this.

[FedericoMusa]

@janiversen Thanks for the guidance.

1. You are spot on regarding the directory context. I re-ran the clean slate test following your instruction (pip install .[development] + cd examples), and the server started perfectly. I missed the directory change in my initial run. I apologize for the false alarm there.

2. Observation regarding the Developer Workflow. While validating the fix, I noticed a small friction point for contributors modifying the code. Since the current command (pip install .) performs a standard install, changes to the source code aren't reflected unless the package is reinstalled.

I did a quick test (see attached screenshots) where I added a log message to the source. It only appeared after I switched to an editable install (pip install -e .).

Since the README mentions creating "pointers directly to the pymodbus directory", I believe the -e flag was likely the original intent, as it allows for real-time updates during development.

Proposal: Would you be open to a PR that:

Adds the -e flag to the installation command to enable dynamic updates?

Adds a brief note about running from examples/ to help future newcomers?

I’m happy to make these small updates to help align the docs with the workflow.

[janiversen]

pull requests are welcome, which I review and comment on.