1. Core concepts

The platform separates two levels: (A) administering a 3PL provider — settings, users tied to that provider, default modules for new companies; (B) operating inside a 3PL company — stock and orders, company users, modules enabled for that company. Physical depots are catalogued under the 3PL operator, not owned by the 3PL company row.

Modules exist in a catalog (monthly or daily price). When you create a 3PL provider you choose a set of default modules (stored as slug list). They act as a template for new companies under that 3PL; afterwards, a super admin can adjust modules per company where the admin UI allows.

• One 3PL provider can have many 3PL companies.
• Each 3PL company has its own internal code (CLI prefix in practice); it is a different field from the provider’s TPL code, even though both are stored as `internal_code` in different tables.
• Current context (active company / selected 3PL) affects which menus and data you see.
• A 3PL provider is itself a company; a second row (3PL company record) with the same details as the provider is the operational record for that same business—not a mistaken duplicate.

2. Roles and permissions (summary)

Creating, editing, and deleting 3PL provider records is generally reserved for super administrators. Viewing a provider and related pages (getting started, audit) is allowed for users who have access to that provider (e.g. 3PL admins). Billing preview and company module invoicing screens are reserved for super administrators.

• Super admin: can create 3PL providers, change internal codes, manage platform-level module screens where they exist.
• 3PL administrator (admin_3pl): operates on behalf of the provider; sees the provider and linked companies, without necessarily having super-admin rights.
• Company users: tied to one or more 3PL companies; do not necessarily see global 3PL administration.

3. Internal codes: TPL (provider) vs CLI (3PL company)

Internal codes keep entities distinct. The TPL prefix is used for 3PL providers. If you leave the field empty at creation, the system may assign an automatic code like TPL plus digits (e.g. TPL000042). You can also enter a manual code (uppercase letters, digits, hyphens) with uniqueness checks.

Technical note: internal code uniqueness is enforced per table (`three_pl_providers` and `clients_3pl`). There is no cross-table constraint that forbids the same character string in both tables — the database can theoretically store the same text as both a provider code and a 3PL company code. Validation on save only checks duplicates within the same table (e.g. `unique:clients_3pl,internal_code` for companies).

Why TPL and client-company (CC) prefixes anyway: generators and the in-app convention (see the “TPL vs 3PL company code” help when creating a provider) keep the two worlds clearly separate — not as a hard uniqueness rule across tables, but for clarity in reports, messages, support, and integrations: you avoid ambiguity when one code could mean two different entity types.

When editing a 3PL provider, internal code changes respect uniqueness only within the providers table and may be recorded in history / activity log.

What does TPL mean?

In the source code (CodeGeneratorService), the TPL prefix is explicitly tied to third-party logistics: the 3PL provider is the entity that performs logistics for its clients. It is not a long “official” label in the UI — it is a short prefix for provider internal codes (e.g. TPL000042).

What does CLI mean here?

Sequential auto-codes for 3PL companies use a CLI-style prefix in the database (CLI000001, CLI000002, etc.). In forms and ANAF suggestions you will also see a CC segment (3PL company code), e.g. TPL…-CC-… — it is not “command-line interface”. The help modal contrasts TPL (provider) vs 3PL company codes.

Why both TPL and CLI — what is each one for?

The app model has two levels: (1) the 3PL provider — the logistics-side record that holds provider settings, default modules, and admin_3pl users (any formal agreement between platform and provider is a super-admin concern, not something 3PL users “administer” as contracts here); (2) the 3PL company — the client company record for orders, stock, and company users. Depot master data (`warehouses`) belongs to the 3PL provider only (`three_pl_provider_id`), not to a 3PL company. TPL and CLI codes are short identifiers, easy to spot in reports and integrations, each for its own level.

• TPL answers: which logistics provider (3PL organization) is this record about? — you see it in provider administration, default modules for new companies, and (for super administrators only) provider-level billing estimates.
• CLI answers: which client company of that 3PL is running operations? — orders, inbound flows, and operational data are tied to the company with the CLI code. Depot records still sit under the 3PL operator; they do not replace the provider’s TPL code.

4. Creating a 3PL provider — wizard steps

From administration, open the new provider form. It is split into logical steps (data, modules, code, optional template from another provider, 3PL administrator).

New 3PL Provider 3PL Providers

5. After save — redirect and onboarding

After a successful create, the app redirects to Getting started for that provider, not to the list. You see a snapshot: number of 3PL companies, depots in that provider’s warehouse catalog, distinct users linked to 3PL companies.

From the same page you get shortcuts: new company (with provider pre-filled via parameter), audit log, 3PL users management, and a link to this workbook. Super administrators also see a billing preview shortcut there.

• If there is no 3PL company yet, the first practical step is to create one.
• Once companies exist, open a company’s detail page for operational setup (users, modules, etc.); manage depots from the 3PL warehouse catalog when your role allows.

6. 3PL companies under a 3PL

New companies are created from the companies flow. When you open the form with URL parameter three_pl_provider_id equal to the provider’s id, the “3PL Provider” field is preselected — reducing selection mistakes.

The company receives an internal code in the CLI namespace (per form/generator rules). Active modules for the company may align with the 3PL template or be adjusted later, depending on your platform configuration.

Deep-link example: /companies/create?three_pl_provider_id=5 (replace 5 with the real id).

New company

7. Users tied to the 3PL provider

The 3PL provider users page lets you attach users to that provider and assign allowed roles (including admin_3pl). This is separate from users tied only to a specific 3PL company.

Actions here may write audit log entries so there is a trace of who added or removed someone from the provider.

9. Audit log and CSV export

The log for a 3PL provider aggregates Activity events where the subject is the provider record itself, or where properties include that provider’s id (e.g. actions on users linked to the 3PL).

You can browse a paginated list and export a CSV file (UTF-8 with BOM for Excel) with columns such as time, log name, description, causer email, subject type, subject id, properties JSON.

• Export is useful for internal compliance or external review over a period.

10. Routes and parameters (reference)

11. Session: selecting 3PL provider and active company

After login, users with more than one context may use screens such as 3PL selection and active company selection. The chosen context drives which data appears in menus, reports, and day-to-day operations.

Switching 3PL context (where available) updates the session so later actions are interpreted in that provider’s scope. Likewise, the active company scopes operational data and modules.

• If some menus are missing, check that the correct company is selected and that your role includes the relevant module.

What is “context” in this app?

The session mainly stores two values that define “where you are” in the app: current_three_pl_id (selected 3PL provider) and current_company_id (active 3PL company). Sidebar, filters, and many queries use them (SidebarComposer, navbar).

In practice: if I change “context”, am I changing the 3PL?

Not only by hand. Context = the pair (3PL in session + active company). Most often you change the active company (another client company / another CLI code): the app then updates the 3PL in session to match the chosen company, so you do not work in a company that belongs to 3PL A while the session still thinks 3PL B.

You change the 3PL explicitly (without picking a company first) when you use the provider selection flow or quick 3PL switch: that updates current_three_pl_id directly; when selecting from the list, the company may be cleared so you pick a company under the new provider.

In short: you change context either by switching to another company (the 3PL in session updates on its own) or by choosing another 3PL as a filter (you usually then pick the company again).

Difference: changing context vs. changing 3PL provider

They are not two unrelated ideas: changing the 3PL provider is one kind of context change, but not the only one.

• Selecting a provider via /select-three-pl (storeThreePlSelection): sets current_three_pl_id and clears current_company_id so you pick a company under that 3PL again. This is the 3PL “filter” change for super admins (and a similar flow for admin_3pl users with multiple providers).
• Switching active company (switchCompany): sets current_company_id and, if the company has three_pl_provider_id, also updates current_three_pl_id to match — they stay in sync (you do not stay on 3PL B in session while working in a company that belongs to 3PL A).
• Quick 3PL switch (switchThreePl on ThreePlProviderController): only changes current_three_pl_id in session (e.g. from a context UI), without going through the company selection screen.
• Leave context (leaveContext, super admin only): clears both current_company_id and current_three_pl_id — back to a more global view with no active company/3PL in session.

Open 3PL provider selection Open company selection

12. Editing a provider and internal code history

When editing a 3PL provider, internal code changes follow the same uniqueness and normalization rules as on create. Changes may be written to a dedicated activity log for code changes (old/new value, user, time).

Use the provider edit screen and any “internal code history” section shown in the UI.

13. UI workflow — steps and button labels

The steps below match the actual screens (Blade views). Labels are those shown through the translation system (English when the app locale is en).

New 3PL Provider

Route: `/three-pl-providers/create` (New 3PL Provider).

Page title: “New 3PL Provider” / subtitle “Add a logistics service provider”.

Top right: “Back to list” (returns to the provider list).

Step bar: ① Main data — ② modules — ③ 3PL administrator — ④ Preview. You can click each step to jump where allowed.

• Step 1 — Main data: card “Provider data”. Optional: “Template from existing provider” (copies default modules). “Internal code” field with placeholder for auto TPL, “Generate code” button, “TPL vs 3PL company code” link (opens the help modal). Enter “Legal name” (required) — without it, optional fields stay gated and the “Next” button on this step may stay disabled. Then “Next” to step 2.
• Step 2 — modules: heading “Default modules for new companies”; “Select all” / “Deselect all”. Footer: “Main data” (back) and “3PL administrator” (forward). The right sidebar shows “Cost estimate” as you toggle modules.
• Step 3 — 3PL administrator: card titled “3PL administrator”. Checkbox “Add 3PL administrator now”. Choose “Existing user” (search) or “New user” (name, email, password, confirmation; optional “Skip welcome tour”). Footer: back to “modules” or “Preview” forward.
• Step 4 — Preview: card “Review and create” with the summary. Buttons: “Back” to step 3 and “Save” (submits the form). On success: redirect to Getting started for that provider.

New company

Route: `/companies/create` (New 3PL company); add `?three_pl_provider_id=ID` to preselect the provider.

Title: “New 3PL company” / intro about adding a 3PL company linked to a 3PL provider.

For super admins, steps are: ① Main data — ② Company administrator — ③ Preview. For other users the wizard has fewer steps — see the progress bar on screen.

• Step 1 — Main data: two cards — “Main data” (left) and “Contact and address” (right). Under “Main data”: required “3PL Provider” dropdown (when shown), required “Cod Intern” label (hard-coded Romanian label in the view), “Legal name”, optional commercial name, CUI/CIF with “Fetch from ANAF”, EORI, registration country. “Contact and address”: email, phone, registered office, description, payment, currency, VAT, “Active company” switch. Footer: “Next”.
• Step 2 — Company administrator (super admin only): “Company administrator” card with “Create admin user” switch. Enable the form for a new user (name, email, password) or leave it off. Then “Preview”.
• Final step — Preview: “Review and create”; button “Create 3PL company” (not “Save”) submits the form.

14. Quick glossary

3PL provider

The logistics organisation between the platform and the companies you serve. In the app it gets a short code that usually starts with the letters TPL so you can spot it quickly in lists and reports.

3PL company

The company that works day to day in the app: orders, warehouse, its own users. It has its own short code (in practice, the CLI family), different from the 3PL provider code — so everyone knows who is the “logistics provider” and who is the “operating client”.

TPL code / CLI code

Two kinds of short codes so people and reports don’t mix up the “logistics organisation” with the “company that operates every day”. TPL code (3PL provider): if you leave the field empty at creation, the system may suggest something like TPL followed by digits (e.g. TPL000042). You can also enter your own code using UPPERCASE letters, digits, and hyphens — it must be unique among providers. CLI code (3PL company): when auto-generated it often looks like CLI plus digits (e.g. CLI000001, CLI000002). In forms or documents you may also see variants with a CC segment (3PL company code). For management: the same-looking code does not mean the same thing — TPL = provider level, CLI/CC = 3PL company level.

Active company (context)

In plain terms: which company you are “looking at” on screen after sign-in and after you pick the company. All lists, orders, and stock refer to that company until you switch it in the selector. Don’t confuse this with changing the 3PL provider in admin screens — that is a different level of work.

Module

A piece of functionality you can turn on for a company — for example a report type or a specific flow. Some modules have a price in the catalogue; what you see in the menu depends on what was enabled for your company.

Activity / audit

A history of important events: who changed what, and when. Used for internal control, audit questions, or when you need to reconstruct “who did what”. It can usually be exported to a file for review.

API

The “official” way other systems in your business (ERP, finance, BI) can read or send data into the app, with the right permissions for each user. Technical documentation is public on the site at /api-docs — IT teams use it to build integrations.

Webhook

A web address you register in the system; when something important happens (for example an order status changes), the app sends an automatic “heads-up” to that address. That helps automation — e.g. updating a table in another tool or triggering a notification — without checking everything by hand.

3PL

Common shorthand for “warehouse management system”. In practice: the part of the app where you track what comes in, what goes out, what is on hand, returns, and warehouse-related reports.

SKU / article

The product record in the catalogue: the code warehouse and office use, the name, the unit (pieces, kg…). Without this step you cannot add lines on purchase or sales orders — everything starts from the catalogue.

PO (Purchase Order)

The order you place with a supplier — which products and how many. When goods arrive, you record receptions “against” this order until you cover what you ordered (or partially, if that is what you agreed).

SO (Sales Order)

The sale to the customer: what you ship and in what quantities. When you mark the delivery as complete in the app (goods have left for the customer), quantities leave stock. If the customer sends something back, the return is linked to this sale so the story stays clear.

Reception

The step where you confirm goods have physically entered the warehouse, usually based on a purchase order. After you confirm, “what you have on the shelf” goes up by the received quantities.

Warehouse

The place where you track quantities — a building, a location, or an internal name. Every inbound or outbound move must clearly state which warehouse it happens in, otherwise stock cannot be followed correctly.

Stock / transaction journal

“How much we have now” for each product and warehouse. Next to that, the history (journal) shows how you got to those figures: receptions, shipments, adjustments. Useful when you need to explain differences or check a delivery.

Return

When the customer sends goods back. You record it in the app linked to the original sale; the quantity goes back into the chosen warehouse so stock and history stay correct.