Concepts

Basic Concepts

This page introduces the fundamental concepts of the pyck framework.

Tenant

In pyck's multi-tenant architecture, a tenant is an isolated customer account that contains all their data. Think of it like an apartment building - each tenant has their own space (apartment) that's completely separate from others, even though they share the same building (software infrastructure). Each tenant can have multiple root-level repositories (warehouses), allowing a single company to manage operations across multiple facilities while keeping data isolated from other companies. This enables pyck to serve many customers on the same platform securely.

Repositories

Repositories are the fundamental building blocks of pyck - any container that can hold goods is a repository. Unlike traditional WMS with fixed location types, pyck lets you create repositories for anything: warehouses, zones, shelves, bins, pallets, trolleys, or even forklifts. They form hierarchical structures where any repository can contain other repositories, creating your warehouse layout through parent-child relationships.

Types of Repositories

pyck features two types of repositories:

• Static Repository: Fixed in place, such as shelves or zones. These cannot be moved.

• Dynamic Repository: Movable and can be repositioned using RepositoryMovements.

Additionally, repositories can be categorized as real or virtual:

• Real Repositories: Physically store and track goods with full stock validation.

• Virtual Repositories: Special repositories that can "create stock out of nowhere" - they bypass stock validation checks. This is essential at warehouse boundaries where you need to introduce new items (receiving) or remove them (shipping). Common virtual repositories include:

  • Receiving: "Incoming Goods" or specific supplier repositories like "Apple Deliveries"

  • Shipping: "Customer Orders" or individual customer repositories

  • Losses: "Damaged", "Stolen", "Missing", "Internal Use"

  • Adjustments: "Inventory Correction"

The granularity of virtual repositories depends on your tracking needs - you might use one general "Incoming" repository or create dozens of supplier-specific ones for detailed tracking.

Repository Structure and Layout

Repositories can be nested within each other, forming the warehouse layout. For example, the "Warehouse Berlin" repository includes Zones A and B, along with inbound and outbound zones. Zone A is a sub-repository of "Warehouse Berlin."

Movements

Movements are the core operational unit in pyck - they represent orders or tasks to relocate inventory between repositories. Unlike traditional systems that simply update database records, movements are executable instructions for workers or machines. Every inventory transfer, whether moving a single item or an entire pallet, is tracked as a movement. This creates a complete audit trail and enables time-travel queries to see inventory state at any point in history. Movements validate stock availability when created (except when sourcing from virtual repositories), ensuring operational feasibility.

pyck supports two types of movements:

1. Item Movement

2. Repository Movement

Repository movements are exclusive to dynamic repositories. When a movement is created, whether it's an item or repository movement, the system verifies order fulfillment by checking if there's sufficient stock available in the outgoing repository to carry out the transfer.

Movement Collections

Movement collections group multiple movements into an ordered sequence - think of them as intelligent task lists. While traditional pick lists only handle item picking, collection movements can orchestrate complex operations mixing item movements (pick 10 units) with repository movements (move entire pallet). They're powerful because they can represent complete workflows like "take forklift to aisle 3, pick up pallet, move to staging, add items, deliver to dock." This flexibility enables optimization of worker routes and equipment usage across diverse warehouse operations.

For example, if we need 10 iPhones in the outbound zone, a movement collection might include:

• Pick 5 iPhones from Box 3 on Shelf 5 and load them onto your trolley.

• Pick another 5 iPhones from Box 14 on Shelf 6 and load them onto your trolley.

• Move the trolley to the outbound zone.

• Move 10 iPhones from your trolley to the table in the outbound zone.

The crucial point here is that when creating movements in a collection, the system performs forward-looking stock validation across the entire sequence. It knows that after executing the first two movements, there will be 10 iPhones on the trolley, making the fourth movement plausible. This is why collections are powerful - they validate the entire chain of operations, not just individual movements in isolation. If you tried to create the fourth movement alone (without the collection context), it would fail because the trolley currently has no iPhones.

If goods are moved from a virtual repository, stock levels are not validated in that repository. Virtual repositories facilitate the transfer of goods in and out of the warehouse.

DataTypes

In pyck, each entity—such as customers, items, or suppliers—can store additional data in a JSON field called "data". To ensure this data is structured and validated, we use DataTypes, which are essentially JSON Schemas. Any data submitted through our API validates against these schemas and ensures data integrity.