Architecture

How Luminar Works is organized

Luminar Works is organized around a small set of core concepts: Business Units, Resources (Assets and Agents), Customers, Sites, Tasks, and Trips. This document explains what each concept is and how they relate. For how to create and manage them in the interface, see the Interface documentation.

A principle that runs through the platform is inheritance: data set at a higher level flows down as the default, and can be overridden at a lower level where operational reality differs. Set things up once at the level where they are usually true, and override only the exceptions.

Business Units in Luminar Works

A Business Unit (BU) is the home base for your planning. Each Business Unit has its own resources and plans. An account can have multiple Business Units, and more can be added as your operation grows.

Each Business Unit has:

• A location — the Business Unit is assumed as the start and end location of a resource's trips.
• A timezone — trips planned in a Business Unit assume the timezone of that Business Unit. Times are stored in UTC and displayed in the Business Unit's timezone, so there is no conflict if a resource moves between Business Units or a Business Unit's timezone needs to change.
• An operating window — see Operating times in Luminar Works below.
• A currency — used should any financial reporting be required.
• A distance unit — miles or kilometers.
• A default speed profile for its resources — any newly created resource associated to the Business Unit has the Business Unit's speed profile by default, maintained thereafter at resource level.
• Billing information — contact, address, and tax number, which appear on customer-facing documentation generated from Luminar Works.
• A Business Type — see below.

Business Types in Luminar Works

Every Business Unit is set up with a Business Type, which shapes how planning works and which resources count towards licenses:

• A Time-Constrained Business Unit plans around the time of the people doing the work. Agents are required to plan, and Agents are the resources that count towards licenses.
• A Capacity-Constrained Business Unit plans around what its equipment can carry or handle. Assets are required to plan, and Assets are the resources that count towards licenses.

The Business Type also determines which task types can be planned:

• Time-Constrained Business Units can plan service tasks only.
• Capacity-Constrained Business Units can plan all three task types: drop-off, pick-up, and service.

Resources in Luminar Works: Assets and Agents

Resources are who and what does the work. There are two resource types, and both exist regardless of the Business Type:

• Assets — equipment, such as vehicles or machinery. Assets hold capacities.
• Agents — people.

In each Business Unit, one resource type is the primary resource (required for planning) and the other is the secondary resource (optional):

• In a Time-Constrained Business Unit, the Agent is the primary resource.
• In a Capacity-Constrained Business Unit, the Asset is the primary resource.

This reflects that different businesses have different requirements — and it matters for execution too: it is the Agent, the person, who will interact with a trip in the field. A Luminar Works mobile app for agents — allowing published trips to be viewed and executed in the field — is coming soon after launch, and is not yet available.

A resource may have its own operating window. Where a resource has no operating window of its own, it defaults to the Business Unit's operating window — see Operating times in Luminar Works below.

Resource states in Luminar Works

A resource is either Active — eligible for planning — or Inactive — ineligible for planning. Setting a resource to Inactive does not affect the Business Unit's subscription license count. Reducing your licensed resource count is a separate action — see the Subscription documentation.

Resources carry speed profiles, which refine travel-time estimates. A newly created resource has its Business Unit's default speed profile, maintained thereafter at resource level. During planning, the primary resource's speed profile is taken into consideration.

Operating times in Luminar Works

Luminar Works takes several operating-time concepts into consideration when planning. Together they determine when trips can start and end, when travel is permitted, and when activity can take place at a location.

The planning horizon in Luminar Works

The planning horizon is the date range selected for a planning run, and is fundamental to how all time windows are interpreted. It is the hard outer boundary of a plan: every trip's start and end must fall within it. In Luminar Core, the planning horizon is a single day. Planning across multiple days is provided by the Multi-day Planning module.

Time windows in Luminar Works

Three windows are taken into consideration during planning, and each constrains its own role:

• The Business Unit operating window — when the Business Unit is active and able to host activity by resources.
• The resource operating window — when a resource may be active and moving. Where a resource has no operating window of its own, it defaults to the Business Unit's operating window.
• The task service window — when a task may be conducted. A task's service window is inherited from its Site by default (which in turn inherits from its Customer), and can be specified at task level — the task's service window is what planning takes into consideration.

How operating and service windows combine in Luminar Works

Where more than one window applies to an event, all of them must be satisfied — the most restrictive constraint applies. Each window constrains its own role: the resource operating window governs when the resource may move; the Business Unit operating window governs when the Business Unit may host activity; the task service window governs when a task may be conducted. For example, a task must be conducted within its service window, and the travel to reach it must fall within the resource's operating window. A resource may arrive at a location before a window opens and wait to be served.

Operating window times in Luminar Works

An operating window has a start time and an end time. A window with the same start and end time is interpreted as 24-hour operation.

An overnight operating window — with a start time later than the end time, such as 20:00–06:00 — is interpreted according to the planning horizon. Within a single-day horizon, it is treated as two operating windows in the day: midnight to the end time, and the start time to midnight (continuing the example, 00:00–06:00 and 20:00–24:00). With the Multi-day Planning module, it expresses continuous overnight operation across days.

Blackout windows in Luminar Works

A blackout window prohibits travel during a defined period. Typical uses include legal or business policies that bar travel during certain hours, and fixed breaks such as a lunch period. Blackout windows are part of the Rest/Break Management module.

• Blackout windows are defined at Business Unit level, and all resources operating for that Business Unit adhere to them.
• A blackout window can recur every day, or be set per day of the week. A full-day blackout can be used to express a non-operating day.
• The purpose of a blackout is to prevent travel; the configuration relates to whether visit activities may proceed during the blackout — for example, if a resource is already at a Site, whether the task's activity may be carried out while travel remains prohibited.

Customers and Sites in Luminar Works

A Customer is who the work is for — the entity that places the order. A Site is a location where work happens.

• A Customer can have multiple Sites — for example, a customer with several stores.
• A Site cannot exist without a Customer.
• A Customer is not associated to a Business Unit. There is no restriction between Customers and Business Units — a Customer's tasks can be serviced from any active Business Unit.

Inheritance: a Site inherits its Customer's data by default — service windows, duration, address, and location — and any of these can differ at Site level. This gives flexibility when a Customer is serviced at more than one location.

Tasks in Luminar Works

A Task is an individual piece of work to be planned. Every task is associated to:

• A Customer — the entity that placed the order.
• A Site — the location where the work happens.
• A Business Unit — so that drop-off or pick-up stock is attributed to the right place on your side, and so that the eligible subset of resources for the task is known.

Every task has a start date and an end date, which define the horizon over which the task must be conducted. On the planning page, filters are applied by Business Unit and date range to determine whether a task may be included in the dataset for planning.

Inheritance: a task inherits its Site's data by default — service windows, duration, address, and location. Service windows and duration can also be specified at task level, to handle the operational requirements of a specific task.

Tasks cannot be split in Luminar Works

Luminar Works does not split tasks — each task is planned as a whole:

• If a task's size is larger than the capacity of the largest available Asset, the task can still be planned manually by dragging it onto a trip — the constraint signals will show the capacity being exceeded — but the Smart Planning module will not split the task across multiple trips.
• If a task's duration is longer than its service window, Luminar Works will not split the task.

For operations with bulk orders, tasks should be split into manageable sub-tasks before being created in Luminar Works — whether entered directly, imported via CSV, or created via the REST API.

Task states in Luminar Works

When a task is created, it is either Ready — eligible for planning — or Blocked — ineligible for planning. A Ready task is eligible to move through the Planning, Planned, and Published states — see Planning states in Luminar Works.

A task can also move backwards through states — for example, from Planned back to Ready if it is removed from a trip, or from Ready to Blocked if it is no longer eligible for planning. Further states will be added as mobile execution becomes available.

A task is set to Blocked by the user, or by your own systems via the REST API. The Blocked state allows tasks to be excluded from planning for operational reasons — for example, stock being unavailable, or an order being canceled by the customer after the task was created in Luminar Works.

Task types in Luminar Works

Luminar Works supports three task types: drop-off, pick-up, and service.

• Drop-off and pick-up tasks typically have sizes, which are taken into consideration when planning on Assets.
• Service tasks do not have sizes.

In Luminar Core, each task is independent — there are no dependencies between tasks.

Trips in Luminar Works

A Trip is the planned sequence of tasks assigned to a resource. Every trip has a defined start and end.

• A trip may extend over multiple days.
• A single resource can be assigned more than one trip within a planning horizon. Trips for a resource are sequential, not concurrent — a resource cannot be double-booked at any point on the timeline.
• The Business Unit is assumed as the start and end location of a resource's trips. Resource-level start and end locations will be available with the Resource Operation module when it is released — it is not yet available. See the Roadmap documentation.
• Trips assume the timezone of their Business Unit.

Capacity and sizes in Luminar Works

Capacities are held on Assets; sizes are held on tasks. In a Capacity-Constrained Business Unit, capacity is taken into consideration during planning: the sizes of drop-off and pick-up tasks are planned against the capacity of the Asset conducting them.

Luminar Core supports one capacity dimension per Asset and a size for each task. Planning against multiple capacity dimensions is provided by the Size-Up module.

Planning states in Luminar Works

Entities move through three planning states:

• Planning — entities that are part of a dataset that is actively being planned. While in the planning state, an entity cannot be edited or deactivated — this prevents contradictions in the data and interference with the session in progress.
• Planned — entities that are associated to a trip.
• Published — planned trip entities that have been confirmed and locked. Publishing is the gatekeeper: only published trips can be exported to CSV, Excel, or PDF, shared to the allocated Agent by email and WhatsApp, or — at general launch — retrieved by external systems via the REST API; published trips are also eligible for mobile execution once the mobile app is available.

Coming soon: A Luminar Works mobile app for agents — allowing published trips to be viewed and executed in the field — is coming soon after launch, and is not yet available.

Map sets and speed profiles in Luminar Works

Luminar Works uses map sets that are updated on a regular basis to determine average travel speeds. Speed profiles are taken into consideration inherently within the map sets — travel-time estimates reflect each resource's speed profile as part of the map data, not as a static adjustment applied on top.

A newly created resource has its Business Unit's default speed profile, maintained thereafter at resource level. During planning, the primary resource's speed profile is taken into consideration.

Users and roles in Luminar Works

At present, the user who creates the account is the Admin, with access to everything.

A fuller roles model is planned and not yet available, anticipated to include:

• Admin — able to maintain subscriptions, users, and account-level settings.
• Planner — able to conduct planning activities and data maintenance.
• Expeditor — able to view and interact with execution aspects, once execution features are available.

Also anticipated: Business Unit–level user association for larger businesses, controlling who can view and edit which business entities.

Luminar Works architecture FAQs

What is the difference between a Customer and a Site?
A Customer is who the work is for — the entity that places the order. A Site is a location where work happens. A Customer can have multiple Sites, and a Site cannot exist without a Customer.

Can one Customer be serviced by more than one Business Unit?
Yes. A Customer is not associated to a Business Unit, so its tasks can be serviced from any active Business Unit.

Why does every task need a Business Unit?
So that drop-off or pick-up stock is attributed to the right place on your side, and so that the eligible subset of resources for the task is known.

Can a task be split across trips?
No. Luminar Works does not split tasks — each task is planned as a whole. If an order is too large for one trip, split it into sub-tasks before creating the tasks in Luminar Works.

Why isn't my task available for planning?
A task must be in the Ready state, belong to the selected Business Unit, and match the date range selected on the planning page. Blocked tasks are ineligible for planning.

Why can't I edit a resource, customer, or task right now?
It is likely part of a dataset being actively planned. Entities in the planning state cannot be edited or deactivated until the planning session ends — this prevents contradictions in the data and interference with the session in progress.

What timezone are my trips shown in?
Trips assume the timezone of their Business Unit. Times are stored in UTC and displayed in the Business Unit's timezone.

Do I need both Assets and Agents?
Only the primary resource type of your Business Unit is required for planning: Agents in a Time-Constrained Business Unit, Assets in a Capacity-Constrained Business Unit. The other resource type is optional.