---
description: >-
  Polylith is a software architecture that applies functional thinking at the
  system scale. It helps us build simple, maintainable, testable, and scalable
  backend systems.
---

# Polylith

![](https://3095132514-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LAhrWK1psIWk5h5zNLV%2F-MN-nQOsqO4ku_lqUgSh%2F-MN-nX3dJ6asRzIpei9B%2Flogo.png?alt=media\&token=995f9b97-efdf-4809-9d60-2707fdbe849b)

## Introduction

Working with Polylith is like having a box with LEGO® bricks:

<figure><img src="https://3095132514-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LAhrWK1psIWk5h5zNLV%2Fuploads%2FUIKLNHpkQXNj3yvLhm24%2Fbrick.png?alt=media&#x26;token=8e5f30f0-0620-4604-b20a-99a137cbacb8" alt=""><figcaption></figcaption></figure>

From here we put together sets of bricks, that are built into services and tools:

<figure><img src="https://3095132514-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LAhrWK1psIWk5h5zNLV%2Fuploads%2FXIzoI1jnlNJ9HbfcqUnp%2Fproject.png?alt=media&#x26;token=5812af7b-d35f-40d2-8b50-741de0cdc888" alt=""><figcaption></figcaption></figure>

We work with all the code from one place, and get all the benefits we have from a monolith:

<figure><img src="https://3095132514-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LAhrWK1psIWk5h5zNLV%2Fuploads%2FubX4FB6ENwlvNDqVvVvm%2Fworkspace.png?alt=media&#x26;token=84edbf2a-aef9-4990-98e8-72a72354dc70" alt=""><figcaption></figcaption></figure>

This gives us a joyful development experience and a high degree of flexibility in how to run the code in production.

If you want to quickly see if Polylith is for you, please jump to the [Sharing code](introduction/sharing-code) page. Another good start could be to [read a blog post](#read-a-blog-post) or continue reading here!

### Sponsoring

Please support the work with Polylith and the poly tool [here](https://cljdoc.org/d/polylith/clj-poly/0.2.18/doc/readme)!

#### Bronze Sponsors

[![](https://3095132514-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LAhrWK1psIWk5h5zNLV%2Fuploads%2FV9TqTUMtIOYZDuOs453W%2Fwide_purple.svg?alt=media\&token=183fc684-0807-4382-97f1-abc373504072)](https://www.scrintal.com)

#### Iron Sponsors

[![](https://3095132514-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LAhrWK1psIWk5h5zNLV%2Fuploads%2FlkXOd0QHcTK4AaoN04F1%2Fadgoji3.png?alt=media\&token=217867a8-f936-4a89-9d01-a225898c76f6)](https://www.adgoji.com)

<div align="left" data-full-width="true"><figure><img src="https://3095132514-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LAhrWK1psIWk5h5zNLV%2Fuploads%2FOzrvRdMQTpmyCeQguE6u%2Ftaehee-sp.png?alt=media&#x26;token=1874271e-1e14-4fe0-8f79-e2147784f407" alt="" width="206"><figcaption></figcaption></figure></div>

### Learn Polylith

There are several ways of learning Polylith:

### Try it out yourself

If you are a Clojure developer, head over to the [poly tool](https://cljdoc.org/d/polylith/clj-poly/CURRENT/doc/readme) documentation.

If you are a Python developer, please visit the [python tool](https://davidvujic.github.io/python-polylith-docs/) documentation.

If you prefer some other language, you can still structure your code as a Polylith [workspace](architecture/2.1.-workspace) and get benefits like decoupled [components](architecture/2.3.-component), a single [development](architecture/2.4.-development) environment, and a flexible deployment situation.

### How it's used in production

Watch when [Sean Corfield](https://corfield.org/) explains how he uses Polylith at World Singles Network:

{% embed url="https://www.youtube.com/watch?v=_tpNKAv4fro" %}

### Look at working code

Go and have a look at these systems:

* The [RealWorld example app](https://github.com/furkan3ayraktar/clojure-polylith-realworld-example-app) in Clojure, written by Furkan Bayraktar
* The [User Manager example app](https://github.com/seancorfield/usermanager-example/tree/polylith) in Clojure, written by Sean Corfield
* The [Polylith project](https://github.com/polyfy/polylith) in Clojure, written by Joakim Tengstrand
* A [Game of life app](https://github.com/tengstrand/game-of-life) in Clojure, written by Joakim Tengstrand

### Watch other videos

Get a high level introduction to Polylith with these three videos:

{% embed url="https://youtu.be/Xz8slbpGvnk" %}
10-minute overview, by James Trunk
{% endembed %}

{% embed url="https://youtu.be/pebwHmibla4" %}
A 39-minute overview of the Polylith architecture, by Joakim Tengstrand and Furkan Bayraktar
{% endembed %}

{% embed url="https://www.youtube.com/watch?v=CCo7T3m6LLM" %}
A 25-minute presentation showcasing how Polylith is used at Greenlabs (with English subtitles) by Jungin Kwon
{% endembed %}

### Listen to a podcast

Jacek Schae interviews the Polylith team in the [ClojureScript podcast](https://clojurescriptpodcast.com/):

* [S4 E21](https://podcasts.apple.com/se/podcast/s4-e21-polylith-with-joakim-james-and-furkan-part-1/id1461500416?i=1000505948894\&l=en) - Polylith with Joakim, James and Furkan (Part 1)
* [S4 E22](https://podcasts.apple.com/se/podcast/s4-e22-polylith-with-joakim-james-and-furkan-part-2/id1461500416?i=1000507542984\&l=en) - Polylith with Joakim, James and Furkan (Part 2)

### Slack

Come and chat with us and other Polylith users in [Slack](https://clojurians.slack.com/archives/C013B7MQHJQ).

### Read a blog post

* [Leveraging Polylith to improve consistency, reduce complexity and increase changeability](https://medium.com/qantas-engineering-blog/leveraging-polylith-to-improve-consistency-reduce-complexity-and-increase-changeability-2031dd3d5f3d) - by Felix Barbalet
* [Understanding Polylith through the lens of Hexagonal architecture](https://medium.com/@joakimtengstrand/understanding-polylith-through-the-lens-of-hexagonal-architecture-8e7c8757dab1) - by Joakim Tengstrand
* [The Monorepo/Polylith Series](https://corfield.org/blog/2021/04/21/deps-edn-monorepo-2/) - Sean Corfield writes about his Polylith journey
* [A fresh take on monorepos in Python](https://davidvujic.blogspot.com/2022/02/a-fresh-take-on-monorepos-in-python.html) - David Vujic introduces Polylith in Python
* [The Polylith architecture](https://medium.com/@joakimtengstrand/the-polylith-architecture-1eec55c5ebce) - How Polylith came to life, by Joakim Tengstrand
* [The origin of complexity](https://itnext.io/the-origin-of-complexity-8ecb39130fc) - The foundational concepts that Polylith is built upon, by Joakim Tengstrand

### Production systems

Enter [the Matrix](https://www.youtube.com/watch?v=fBDifUjNzbQ) and have a look at different [production systems](https://cljdoc.org/d/polylith/clj-poly/CURRENT/doc/production-systems).

![](https://3095132514-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LAhrWK1psIWk5h5zNLV%2Fuploads%2FE8In8VYbkZ1mcp2rn9b0%2Fimage.png?alt=media\&token=2e2afb46-ebb2-484c-b7d1-611c491615fa)

### Read the documentation

If you prefer reading documentation, then you’re already in exactly the right place!

Note that Polylith documentation is split into two parts:

1. This high-level documentation, which describes how Polylith works and the problems it solves. It tries to remain language agnostic, but does use Clojure in the code examples.
2. The [poly tool](https://cljdoc.org/d/polylith/clj-poly/CURRENT/doc/readme) documentation, which describes how to work with a Polylith codebase in Clojure. There is a reworked version of the doc in Japanese [here](https://zenn.dev/shinseitaro/books/clojure-polylith).

Content:

* Polylith - what is Polylith?
* Sharing code - how Polylith addresses the sharing problem
* Testing incrementally - how a Polylith system can be tested incrementally
* Polylith in a nutshell - a walkthrough of the building blocks of Polylith.
* Workspace - were we put everything.
* Component - our composable building block (brick).
* Base - building block (brick) that exposes a public API
* Project - deployable artifact made of a set of bricks&#x20;
* Development project - the place where we work with all our bricks
* Bring it all together - a short example
* Simplicity - how Polylith simplifies the design
* poly tool - overview of the poly tool
* Current architectures - a walk through of common architectures
* Advantages of Polylith - how Polylith differ from other architectures
* Transitioning to Polylith - step by step guide on how to transition to Polylith
* Production systems - list of companies using Polylith in production
* Why the name "Polylith"?
* Videos
* FAQ - Frequently Asked Questions
* Who made this?

## What is Polylith?

Polylith is a software architecture that solves some of the fundamental challenges in building backend systems. Those challenges are:

* It's difficult to share our code across teams and services
* We lack a shared language for communicating architectural concepts
* As our codebases grow, they tend to become a complex mess that is hard to change and test
* We try to mimic our complex production environments in our development environment
* Our systems take too long to test, build, and deploy

Polylith addresses these challenges by introducing simple, composable, LEGO-like bricks, which can easily be shared across teams and services. The choice of bricks determines what each artifact does and how it's exposed.

To make the development experience even more delightful, we've also built a [tool](https://cljdoc.org/d/polylith/clj-poly/CURRENT/doc/readme) which gives instant creation of the various building blocks, incremental tests (only test the code that's impacted by the last changes), and project visualization.

## What isn't Polylith?

* Polylith isn't a framework and does not come with ready to use functionality.
* Polylith isn't a library.&#x20;
* Polylith isn't a tool (but has tooling support for Clojure and Python).

## What programming languages are Polylith for?

Polylith is language agnostic, and it should be possible to use it in almost any programming language. We in the Polylith team have only used it with the functional language [Clojure](https://clojure.org) so far, but there is nothing stopping someone from using it in a procedural language like [C](https://en.wikipedia.org/wiki/C_\(programming_language\)), or an object oriented language like [Java](https://en.wikipedia.org/wiki/Java_\(programming_language\)) (remember that we have [tooling support](https://davidvujic.github.io/python-polylith-docs/) for [Python](https://en.wikipedia.org/wiki/Python_\(programming_language\)) already). Even without tooling support, you will get most of the benefits.
