Polylith Architecture

6 min readMar 7, 2024

I have recently begun experimenting with Poly Architecture for the development of Python projects and have found it to be an excellent method for organizing Python projects and reducing complexity in the development process.

Poly Architecture appears to be well-suited for rapid experimental development. However, it is important to note that there is no one-size-fits-all solution, and it may not be suitable for all types of projects. In this article, I will briefly discuss the concept of Poly Architecture and share my experiences using this architecture and the plug-in tools that are built on top of Poetry, a fantastic dependency management tool.

One of the standout features of this architecture is the inclusion of plug-in tools that are built on top of Poetry. These tools are extremely helpful for managing Python project dependencies and automatically setting up project-specific virtual environments with a single command, saving a significant amount of time.

What problem does Polylith solve?

I quote from original source:

Polylith offers a solution to the Microservice vs Monolith tradeoffs. Microservices are great, but the standard kind of setup will probably introduce a new set of problems:

- Source code is spread out in several repositories.
- Duplicated code.
- Shared code need to be packaged as libraries - that means even more repositories.
- Microservices running different versions of tools and dependencies, potentially also different Python versions.

Polylith addresses these types of issues, with simplistic solutions. In addition to that, Polylith is very much about the Developer Experience. It has support for REPL Driven Development - a workflow that makes coding both joyful and interactive.

Simple is better for me

In my experience, Poly Architecture provides strong support for fast-paced development by maintaining a monorepo codebase in a single location and enabling code sharing between multiple services. Additionally, the architecture offers all of the convenient features of Poetry. This results in a streamlined development process, providing a clear and organized view of the project.

What is Polylith?

The concept was introduced in Clojure which they call “service level building blocks”. One definition is a software architecture that enables us to construct “modular monoliths” using composable building blocks. it helps us build simple, maintainable, testable and scalable software or components. Another definition, it’s a project code repository organization approach like monorepo but quite different in content structure. It came with its own set of terminologies and concepts.

Short Introduction

The Inspiration of polylith came from Lego@ building, where we start with a base, then put together a set of bricks, that are built into services and tools. The Base is the public interface, it handles external calls and the project handle build and deployment.

Polylith promotes use of functions as building blocks for code from which everything is created for these reasons:

Encapsulation — function hide their implementation and only exposure signature
Simplicity — functions have single responsibility
Stateless — function just a piece of execution code
Purity — function can take control of side effects

Library — is kind of the same for the library we already know and use today. It lives in its own namespace.
Components — are high level blocks (aka. Bricks) which remove the need for layers.
Base — is a special type of building block (Brick) that expires it’s functionality via public API eg. REST, Queue..etc
Brick is the common name for component or base
Project specify libraries and components should be package together for deployment as service
Development Project holds libraries, components and base
Workspace store all building blocks and configuration for the project.

Now, let’s dive into key components of Polylith Architecture.

Workspace

This is a single place for all the code and projects which is describe by file workspace.toml the core components as follow:

▾ workspace
  ▸ bases
  ▸ components
  ▸ development
  ▸ projects

Component

Components are the main building blocks in Polylith. A component is an encapsulated block of code that can be assembled together with a base.

Each component lives on own folder under the component directory

▾ workspace
  ▾ components
 ▾ mycomponent
   ▸ src
   ▸ test
   ▸ resources

Base

Bases are the building blocks that expose a public API to the outside world. Base uses components and libraries assembled as service. This allow encapsulation and composability of private implementation (similar gang of 4 design patterns).

▾ workspace
  ▾ bases
 ▾ mybase
   ▸ src
   ▸ test
   ▸ resources

Project

Project is a placeholder for deployable artifacts which combine one base with multiple components or libraries.

▾ workspace
  ▾ projects
 ▾ myproject
     Deps.edn

Development Projects

The development project is where we work with the entire codebase.

Polylith Plug-in

First we need to have Poetry install, after that include this Polylith Tool — helper to manage the project artifacts.

create the structure of our workspace, bases, components, projects and development project.
test our codebase incrementally.
vizualize the workspace so we can understand and communicate about our codebase and architecture.

The Python tools for the Polylith Architecture is available as two options:

> A Poetry plugin. The plugin will add Polylith specific features to Poetry.

> A standalone CLI supporting Hatch, PDM and Rye (and Poetry).

For poetry install

$ poetry self add poetry-multiproject-plugin

Add the Polylith plugin:

poetry self add poetry-polylith-plugin

Now, we are ready to create project workspace.

Create a Polylith Workspace

```
#Create a directory for your code, initialize it with git and create a basic Poetry, Hatch or PDM setup:

$ git init
$ poetry init
$ poetry poly create workspace --name my_namespace --theme loose
```
Create a virtual environment for the workspace.
```
poetry install
```
By default this installs the library in a shared virtual environment. so in order to keep the .venv for the project only. Add this file name:poetry.toml to your project with following content:
```
[virtualenvs]
path = ".venv"
in-project = true
```

Create a component

$ poetry poly create component — name my_example_component

Create a project

$ poetry poly create project - name my_example_project

Now, you should have workspace.yaml file with content like this

[tool.polylith]
namespace = "my_example_namespace"
[tool.polylith.structure]
theme = "loose"
[tool.polylith.tag.patterns]
stable = "stable-*"
release = "v[0–9]*"
[tool.polylith.resources]
brick_docs_enabled = false
[tool.polylith.test]
enabled = true

And a project structure looks like this

workspace/
  bases/
  components/
  development/
  projects/

  pyproject.toml
  workspace.toml

  README.md

For a full sample project implementation I did, see here: https://github.com/PavAI-Research/pavai-c3po

Advantages

Polylith’s single development project allows us to work with all of our building blocks in one place. This disconnects our development experience from our chosen deployment architecture

Here’s what the value proposition the author promotes:

For production deployment — Polylith allows us to delay our deployment decisions, it also allows us to easily change our deployment architecture, when the need arises. That’s because Polylith makes it easy to recombine our components into any number of services and deploy them to meet our performance needs.

In summary

I think this a well define architecture for fast development, however, I wish the plug-in tool have a bit more functionality for component lifecycle management. other than, after apply this to a project I really like this architecture and approach.

I hope you find this useful.

Have a nice day!

Credit:

The team who created Polylith → nice work!

https://polylith.gitbook.io/polylith/conclusion/who-made-polylith

Python tools for the Polylith Architecture

https://davidvujic.github.io/python-polylith-docs/