# Polylith Concepts

> Provides foundational knowledge about Polylith architecture, including the glossary (bases, components, projects, workspaces), theme layouts, and package manager mapping. Use this when you need to understand Polylith terminology or how the repository is structured conceptually before taking action.

- Skill: `davidvujic/polylith-concepts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add davidvujic/polylith-concepts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/davidvujic/polylith-concepts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: davidvujic (https://skillmd.com/u/davidvujic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/davidvujic/polylith-concepts

---


# Polylith Concepts & Glossary

## Glossary

### Bricks
The fundamental units of code in Polylith — **components** and **bases**. Bricks are reusable, isolated, and organized under a single **namespace**.

### Components
Reusable, isolated bricks that implement business logic or capabilities. Components are consumed by bases and by other components, never the other way around.

### Bases
Bricks that serve as the **entry point** of a deployable application — for example HTTP APIs, CLIs, message-queue consumers, AWS Lambda handlers, GCP Cloud Functions, or scheduled jobs. A base wires together components and exposes the application to its runtime.

### Namespace
The top-level Python package name under which all bricks live (e.g. `mycompany`). Defined once in `[tool.polylith].namespace` in `workspace.toml`; shared by every brick.

### Workspace
The root directory of a Polylith repository. Contains `workspace.toml`, the root `pyproject.toml` (which **is** the development project), the `bases/`, `components/`, `projects/`, and `development/` directories, and a single shared lock file.

### Projects
Lightweight `pyproject.toml` configurations under `projects/<name>/` that **reference bricks** to produce deployable artifacts (Docker images, wheels, Lambda packages). Projects contain no Python source code of their own.

### Development Project
The root `pyproject.toml` itself — a single, unified Python environment that includes **every** brick and **every** dependency (production and dev). Used for local development, REPL sessions, and notebooks under `development/`.

### Dependencies
- The **development project** (root `pyproject.toml`) holds **all** dependencies, including dev-only ones.
- Each **project** under `projects/` holds only its **production** dependencies.
- With **uv workspaces**, individual projects don't need to pin third-party versions — the root `pyproject.toml` and the shared lock file pin versions centrally.

## Package & Dependency Management mapping

The `poly` CLI is package-manager-agnostic — only the **command prefix** changes. Each SKILL.md repeats the prefix detection rule inline so the agent doesn't need this README to act. The full table:

| Tool                          | Detection signal                                                       | Command prefix    |
|-------------------------------|------------------------------------------------------------------------|-------------------|
| **uv** (recommended)          | `uv.lock` present, or `[tool.uv]` in `pyproject.toml`                  | `uv run poly …`   |
| **Poetry**                    | `[tool.poetry]` in `pyproject.toml`, `poetry.lock`                     | `poetry poly …` (via `poetry-polylith-plugin`) |
| **PDM**                       | `[tool.pdm]` in `pyproject.toml`, `pdm.lock`                           | `pdm run poly …`  |
| **Hatch**                     | `[tool.hatch]` in `pyproject.toml`                                     | `hatch run poly …`|
| **Rye**                       | `requirements.lock` + `[tool.rye]`                                     | `rye run poly …`  |
| **Activated virtualenv**      | `$VIRTUAL_ENV` set, or none of the above                               | `poly …`          |

If multiple signals are present, prefer the lock file that exists, then `[tool.<x>]` markers, then plain `poly`.

## Themes

`[tool.polylith.structure].theme` controls the on-disk brick layout:

- **`loose`** (recommended) — flat `<bricks_dir>/<namespace>/<brick>/` directories with tests in a top-level `test/` folder. Used by `python-polylith` itself and by most public examples.
- **`tdd`** — each brick is its own directory with `src/` and `test/` siblings.

> The CLI default for `poly create workspace --theme` is **`tdd`**. Always pass `--theme loose` explicitly when loose is wanted.