Docs Confusion

[michealroberts]

I'm kind of confused by the documentation.

Disclaimer: I come from the Typescript world of apps (e.g., a REST API, a web single-paged application) etc, so the structure is hard to conceptualise in my mind. I therefore had a number of questions.

In the documentation, there is talk of libraries, bricks, bases, components and projects. I don't think the documentation outlines the differences sufficiently for understand, I have read (and re-read) the documentation (specifically this page and this page).

For me, a library is a package, and a project is an app as equivalents in the Typescript/Javascript ecosystem. And components are similar to some common or shared package that does not depend on any of the packages and may depend on first principles / primiatives.

Yet we have bases.

Described as:

Bases are the building blocks that exposes a public API to the outside world.

So, bases are apps? Bases to be mean something WAAAAAAY more fundamental than apps 🤔 They form the base of something else, not an exposure to the outside world. That is an application (be that CLI, a RESTful API, a gRPC server / client etc etc).

So what are projects? Libraries ... or more applications? so what are components? Even smaller libraries more modular libraries?

Then there is talk of libraries, but no indication of how to create them and where to locate them in the paradigm presented.

I'd certainly that this is a combination of my comprehensive but the documentation is definitely confusing.

I'm just left very confused at the decisions and thinking behind the naming conventions behind the directory structures.

Surely apps / packages / components makes more sense than bases / projects / components ... ?

Really keen to here what each of them would do, some examples of what you would put in each and why things were name the way they have been named.

It's almost like the setup was to follow "complex is more simple than simple", and the mental model presented takes a lot of explanation and reading.

Whereas, if I said application, package and component I would argue that ANY developer, coming from other frameworks / languages, would find the mental model far less burdensome.

For me, this is very much needed in the Python ecosystem, but I am just a little confused by the execution.

---

Of course, I will disclaimer this by saying thank you to the authors 🥳 for creating an awesome tool and I:

Happy to learn and be hit with facts and logic as to why I should implement a monorepo in this way.

[DavidVujic]

Hi @michealroberts! Thank you for sharing feedback about the docs, much appreciated. I have probably put too much focus on the Python implementation from a tech perspective - the install process, the commands and the way it interacts with tools like Poetry and such. I have relied a lot on the official Polylith architecture docs, where it is explained more in detail - even if those docs often are from a Clojure perspecitve.

I think some of the confusion might be the naming thing that is used in the Python community in general: packages. I think that's unfortunate and causing a lot of unnecessary confusion. Packages are often used to describe installable libraries, but there's also namespace packages, that basically are Python files put in folders (that are part of your source code).

---

From a Polylith perspective, here's an attempt to clear things out:

Library- the third-party things you install with pip or poetry add. Examples: FastAPI, requests, Pydantic, SQLAlchemy.

Base - a base is where you would put the entry points to your app or service. If you use FastAPI or Flask, you would have the API endpoints added there. So that's part of your source code. Python files in one or several folders. A base ideally don't contain much logic other than the registering of endpoints, in a similar way as the View in MVC, or an "adapter" in the Hexagonal architecture.

Component - the actual implementations of the features. Small building blocks that you combine to build features from. These blocks are the ones a base would import and use.

Project - this is where you collect the source code needed, typically one base and several components. The simplest example would be a single pyproject.toml file. The deployable artifact: the service or app that you can install and run. Similar to the package.json file, often with some Make targets or Docker files. But not containing any Python source code.

[DavidVujic]

If you are familiar with the Hexagonal Architecture, here's an article that I think explains how Polylith relates to it in a clear and detailed way, written by Joakim Tengstrand: https://medium.com/@joakimtengstrand/understanding-polylith-through-the-lens-of-hexagonal-architecture-8e7c8757dab1