Locations

Locations, Devices, and User Management

Audience: Programmer

Overview

pyck provides a comprehensive location and device management system within the Management Service. This system enables physical warehouse layout mapping, device tracking, user check-in/check-out functionality, and inventory repository association with specific locations.

Core Entities

Location

Represents a physical area within the warehouse (e.g., workstation, zone, dock).

Field	Type	Description
id	UUID	Unique identifier
name	String	Location name (unique per tenant)
tenantID	UUID	Owning tenant
dataTypeID	UUID	Optional custom data type
data	Map	Custom fields defined by data type

Device

Represents a physical device (scanner, tablet, workstation terminal).

Field	Type	Description
id	UUID	Unique identifier
name	String	Device name (unique per tenant)
tenantID	UUID	Owning tenant
dataTypeID	UUID	Optional custom data type
data	Map	Custom fields defined by data type

DeviceLocation

Associates a device with a location. A device can only be assigned to one location at a time.

Field	Type	Description
id	UUID	Unique identifier
deviceID	UUID	Associated device
locationID	UUID	Associated location

DeviceUser

Tracks which user is currently checked-in to a device. Only one user can be checked-in to a device at a time.

Field	Type	Description
id	UUID	Unique identifier
deviceID	UUID	Associated device
userID	UUID	Checked-in user

Entity Relationships

Location ──────────────────────────────────────────┐
    │                                              │
    ▼                                              │
DeviceLocation ◄─── Device ◄─── DeviceUser ───► User
                        │
                        │
                        ▼
              InventoryRepository
                 (location_id)

Key relationships:

• Location → DeviceLocation: One-to-many (a location can have multiple devices)

• Device → DeviceLocation: One-to-one (a device is at one location)

• Device → DeviceUser: One-to-one (only one user per device)

• User → DeviceUser: One-to-many (a user can have check-in history)

• Location → Repository: One-to-many (repositories can reference a location)

GraphQL Operations

Creating a Location

mutation CreateLocation($input: CreateLocationInput!) {
  createLocation(input: $input) {
    location {
      id
      name
      data
    }
  }
}

Variables:

{
  "input": {
    "name": "Workstation-A1"
  }
}

Creating a Device

mutation CreateDevice($input: CreateDeviceInput!) {
  createDevice(input: $input) {
    device {
      id
      name
      data
    }
  }
}

Variables:

{
  "input": {
    "name": "Scanner-001"
  }
}

Assigning a Device to a Location

mutation SetDeviceLocation($input: CreateDeviceLocationInput!) {
  setDeviceLocation(input: $input) {
    DeviceLocation {
      id
      deviceID
      locationID
    }
  }
}

Variables:

{
  "input": {
    "deviceID": "device-uuid-here",
    "locationID": "location-uuid-here"
  }
}

To remove a device from its location:

mutation UnsetDeviceLocation($id: ID!) {
  unsetDeviceLocation(id: $id) {
    deletedID
  }
}

User Check-In

When a user starts working at a device:

mutation CheckInUserDevice($input: CheckInUserDeviceInput!) {
  checkInUserDevice(input: $input) {
    deviceUser {
      id
      deviceID
      userID
    }
  }
}

Variables:

{
  "input": {
    "deviceID": "device-uuid-here"
  }
}

The userID is automatically derived from the authenticated user's token.

User Check-Out

When a user finishes working at a device:

mutation CheckOutUserDevice($input: CheckOutUserDeviceInput!) {
  checkOutUserDevice(input: $input) {
    deviceUser {
      id
      deviceID
      userID
    }
  }
}

Variables:

{
  "input": {
    "deviceID": "device-uuid-here"
  }
}

Assigning a Location to a Repository

When creating or updating an inventory repository, you can associate it with a management location:

mutation CreateInventoryRepository($input: CreateInventoryRepositoryInput!) {
  createInventoryRepository(input: $input) {
    inventoryRepository {
      id
      name
      locationID
    }
  }
}

Variables:

{
  "input": {
    "name": "Shelf-A1-001",
    "type": "static",
    "locationID": "location-uuid-here"
  }
}