Growing into a larger monorepo - sub-namespaces?

[gwdekker]

Dear all, David,

We have been happily and succesfully running a polylith powered monorepo (uv backed, but not using workspaces). Very happy with the setup!

I have a question though. We are now in a phase where we have multiple software systems (each managed and used and deployed by one team) hosted in the same repo. Most of them have several bases, several components, and several projects. We have assigned prefixes to each software system to get components that are specific to one software system grouped a bit. The list of components starts however to become very long (longer than one screen of scrolling). This makes it harder to find which components are actually meant and maintained for common use across the software systems.

I am considering to introduce a new folder structure. Within both components and bases we would add folders with the corresponding software system as name, so components specific to that software system could live there, while components that are shared across software systems are still on the components or bases root level. I would still want to consider components on the level /component/system_name/component_name to be considered a component.

If I would in the relevant pyproject.tomls change the bricks table from the format "components/myrepo/mycomponent" = "myrepo/mycomponent" to "components/myrepo/mysoftwaresystem/mycomponent" = "myrepo/mycomponent", would that work?

Are there others taht have made similar considerations, and have some ideas on how to handle this? My requirements: I want to keep it very low friction to create shared components (as now), so i don't want to do any uv workspace like stuff. I do however want to make it easier for a developer to get an overview of which components are shared across software systems, as opposed to components that are only shared within a software system.

[DavidVujic]

Great to hear that you like Polylith! ⭐

I think I understand the problem about the components. I haven't worked in really large Polylith monorepos (at most having about 40-50 components), but know that there are teams out there with 200+ components. In the Clojure community there's a couple of large Polylith Monorepos in that size.

Even though it makes sense to group them by business domain or team ownership, what gets lost is the ability to share components across the domains. From my experience, there's much more code in common than one might think, even for domains that are not directly connected. Polylith aims to remove the "barriers" by the LEGO style smaller components, all of them ready to be used by anyone needing them.

You can still have a larger component, with sub-namespaces that are more domain specific. But all projects using it will get the entire component. For reference, and inspiration, here's some of the larger repos from the Clojure community using the flat style Polylith components: https://cljdoc.org/d/polylith/clj-poly/0.2.21/doc/production-systems

How many components do you have today? Maybe you can even share a screenshot, that would be very cool to see!

[gwdekker]

Right now we have about 120 bricks in total, and we deploy different apps from the repo. I think you slightly misunderstood my question, so I will try to clarify a bit more. I am looking to see if the following pattern is possible and recommended/in use by others. suppose we have apps Apollo and Mars. Both apps have several bases as they have some separate microservices to deploy. The apps are maintained by separate teams that cooperate but do not overlap - so nobody has full overview over the full codebase. We have shared components that are meant to be shared between apps - in this example, logging and some initialization routines in `init`. In practice, in our case we have about 5-6 apps. Suppose a developer of app Mars wants to see if there is already some shared logic for logging. How does she distinguish between a component that is written and maintained for use within one app, or one that is already ready for common use? the way we do that in our monorepo right now: we use a flat structure with prefixes per app. So suppose that we have a common logging component, but also one for apollo only (this one contains for example tagging of the apollo app components in the logs, or handlers that log to slack channels belonging to the apollo team). So the repo structure in the components folder could look like this: ``` /apollo_init /apollo_data_ingestion /init /logging /mars_logging /mars_domain /mars_user_service /mars_utils ``` This worked fine, but by now with 5-6 apps and 100-ish components its hard to find the common components within the noise. So I am considering to move towards: ``` /apollo/apollo_init /apollo/apollo_data_ingestion /init /logging /mars/mars_logging /mars/mars_domain ``` and so on. If I then would write ```"components/repo_name/apollo/apollo_init" = "repo_name/apollo_init"``` in the pyproject.toml, would that work and still allow me to consider `apollo_init` as a standalone component, and for example do `from myrepo.apollo_init import baz` ? And would you think this is a valid way of still keeping a flat-ish structure (the actual namespace of components would be flat, but in the IDE you could more easily focus on just the common components and the ones for your app)? Op wo 18 jun 2025 om 19:18 schreef David Vujic ***@***.***>:

…

Great to hear that you like Polylith! ⭐ I think I understand the problem about the components. I haven't worked in really large Polylith monorepos (at most having about 40-50 components), but know that there are teams out there with 200+ components. In the Clojure community there's a couple of large Polylith Monorepos in that size. Even though it makes sense to group them by business domain or team ownership, what gets lost is the ability to share components across the domains. From my experience, there's much more code in common than on might think, even for domains that are not directly connected. Polylith aims to remove the "barriers" by the LEGO style smaller components, all of them ready to be used by anyone needing them. You can still have a larger component, with sub-namespaces that are more domain specific. But all projects using it will get the entire component. For reference, and inspiration, here's some of the larger repos from the Clojure community using the flat style Polylith components: https://cljdoc.org/d/polylith/clj-poly/0.2.21/doc/production-systems How many components do you have today? Maybe you can even share a screenshot, that would be very cool to see! — Reply to this email directly, view it on GitHub <#350 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AI3UPMPRT64CGYE7AZCIZOD3EGNNHAVCNFSM6AAAAAB7SUN5R6VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNJRGE4TQNA> . You are receiving this because you authored the thread.Message ID: ***@***.*** com>

[DavidVujic]

Thank you for clarifying! 🙏

The Polylith tool would consider everything within the apollo folder as one component. If you want the individual projects to only include some of the sub-folders of that one I think it could work as you describe. But the "from" "to" part would probably need to repeat the structure (i.e. having the apollo folder in-between). Otherwise the imports wouldn't be resolved correctly.

If it isn't an issue for the individual projects to get everything within the apollo component, I would just do that (including the entire component). The tradeoff would be including code that isn't used in the project, though. If you only include the "sub-components" there could be a risk of one of those using code in a sibling folder or top folder without noticing until runtime.

[DavidVujic]

To me it also sounds like a really good idea to have the apollo folder, rather than the prefix. Then you can aim to have the apollo-specific code as "lightweight" as possible, and extract code that can be a generic component. I've done something similar in the Polylith tooling repo itself: the Poetry and Hatch-specific things in it's respective component. But the parts that are non-specific as smaller components outside of it.

[gwdekker]

Thanks for the response! I will consider what the best way forward is going to be. Op vr 20 jun 2025 om 18:55 schreef David Vujic ***@***.***>:

…

To me it also sounds like a really good idea to have the apollo folder, rather than the prefix. Then you can aim to have the apollo-specific code as "lightweight" as possible, and extract code that can be a generic component. I've done something similar in the Polylith tooling repo itself: the Poetry and Hatch-specific things in it's respective component. But the parts that are non-specific as smaller components outside of it. — Reply to this email directly, view it on GitHub <#350 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AI3UPMP4Y7ISHD3NQQV6LEL3EQ4H3AVCNFSM6AAAAAB7SUN5R6VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNJTGI3DOMI> . You are receiving this because you authored the thread.Message ID: ***@***.*** com>