Show HN: Modguard – a lightweight Python tool for enforcing modular design

Hi HN! We are excited to show you modguard - a Python tool we built to enforce a modular, decoupled package architecture.

We built modguard to solve a recurring problem that we've experienced on software teams - code sprawl. Over time, cross-module imports would tightly couple together what used to be independent domains, and eventually create "balls of mud". This made it harder to test, and harder to make changes. Mis-use of modules which were intended to be private would then degrade performance and even cause security incidents.

This would happen for a variety of reasons:

- Junior developers had a limited understanding of the existing architecture and/or frameworks being used

- It's significantly easier to add to an existing service than to create a new one

- Python doesn't stop you from importing any code living anywhere

- When changes are in a 'gray area', social desire to not block others would let changes through code review

- External deadlines and management pressure would result in "doing it properly" getting punted and/or never done

Attempts to fix this problem always came up short. Inevitably, standards guides would be written, and stricter attempts would be made to enforce those guides. Teams would lead developer education efforts, and restrict code review. These approaches each had their own flaws, and didn't scale.

The solution is to explicitly define a module's boundary and public interface in code, and enforce those domain boundaries through CI. This means that introducing a new cross-module dependency required explicitly changing the public interface or the boundary itself. This is a significantly smaller and well-scoped set of changes that can be maintained and managed by those who understood the intended design of the system.

modguard is:

- fully open source

- able to be adopted incrementally

- implemented with no runtime footprint

- a standalone library with no external dependencies

- interoperable with your existing system (cli, generated config)

We hope you try it out! We’d love your feedback.

Github - https://github.com/Never-Over/modguard

Docs - https://never-over.github.io/modguard/

admin@0x63problems.dev