[logarhythm]

Thanks for the feedback, we appreciate it.

It's tricky to pick the right level of detail when explaining an idea like Polylith. If we could precisely identify the level of understanding of the reader, then we could tailor the content to perfectly match their experience level and vocabulary. Unfortunately, we can't do that, so we have to pick a middle ground, where we probably over explain some concepts, and under explain others.

However, we'd be grateful if you could give us some specific examples of sections or pages that you didn't find useful or enlightening.

[Kinrany]

Re: choosing the right level of detail, I think it's preferable to start with people who already have all the necessary background knowledge (but don't necessarily know Clojure since the architecture is intended to be language-agnostic). Once that works, the documentation can be augmented to be easier to understand to people who don't have the background knowledge yet.

[Kinrany]

It seems there are several independent ideas somewhat mixed together.

The idea number 0 is component interfaces. They seem equivalent to plain old interfaces in all the other languages. (Except some reflection may be necessary in statically typed languages to process the lists of functions in a generic way?)

The idea number 1 is bases. They are domain-agnostic adapters that convert component interfaces (aka language-native interfaces) into language-agnostic interfaces. (Except they seemingly do include domain logic because they combine several components before exposing them?)

The idea number 2 is project layout, I think? It appears to be more of a supporting convention at best, not sure.

[tengstrand]

We have a similar question in the FAQ, so I just copied the Q/A here (https://polylith.gitbook.io/polylith/conclusion/faq)!

Question: What parts of Polylith are important and what are just “cermony”?

Answer: The short answer is that all parts are needed:

interface: Enables functionality to be replaced in projects/artifacts.

component: The way we package reusable functionality.

base: Enables a public API to be replaced in projects/artifacts.

library: Enables global reuse of functionality.

project: Enables us to pick and choose what functionality to include in the final artifact.

development: Enables us to work with all our code from one place.

workspace: Keeps the whole codebase in sync. The standardized naming and directory structure is an example of convention over configuration which enables incremental testing/builds and tooling to be built around Polylith.

I also want to add one thing, and that is that Polylith combines the LEGO-like blocks of code (components/bases) outside of the language itself. In Clojure we use tools.deps, but in other languages we would use other tools, like Maven in Java, to combine the different source directories into projects (that is built into aftifacts in the end, like libraries, tools and services).