Setup, concepts (hierarchy, assets, shifts, access)

Setup is the least frequently visited nav group for a day-to-day operator, it’s where an admin models the plant, connects data, and configures rates/workforce. Setup itself only holds a short, direct path now (Getting Started plus Plant Structure). The rest of what it used to list directly, KPI & Alarm Rules, Products, Codes, Workforce, and Rates & Costing, are reached from the Settings page instead (/settings, in the Admin nav group), which groups every tenant-level setting with a current-value summary and a link to the screen that owns it. This page covers the plant-modeling, rates, and workforce half of that territory. Edge/device concepts (gateways, sources, tags, tag discovery, the Signal inbox, kiosk) are covered separately in Setup, edge and devices.

What’s in this area

Every screen above stays fully reachable by direct link or bookmark even where it no longer has its own row in the sidebar, only its rail entry moved, nothing was removed. See How to find your tenant settings in one place for the Settings page itself, and How to navigate quickly for the command palette.

Users, Audit Log, and Plan & API live in the Admin nav group (/users, /audit, /account). One more Admin-group item, Operations (/ops), is visible only to super_admin and requires two-factor authentication, it’s the doorway into the console covering Software/Releases, Tenants, Demo, System health, Errors, and cross-tenant Audit on its own left rail. They are covered below as the access and fleet-governance half of administration.

(Login itself, /login, isn’t inside this nav group, it’s the public gate in front of it, but is covered here since it’s the first thing any new user does.)

Domain objects

The ISA-95 hierarchy: site → area → work-center → machine

Spall models a plant as a tree following the ISA-95 convention: site (a physical plant) contains areas, which contain work-centers, which contain machines. Every KPI rollup (Facility Map, Node Detail) is scoped to a node in this tree via node_type + node_id. The Plant Structure screen both browses and builds that tree, every row has an “Add …” affordance for its child level (Site → Add Area, Area → Add Work Center, Work Center → Add Machine), so a brand-new tenant can go from nothing to a modeled plant without a gateway or device in hand yet (config-first, see “The onboarding path” below). A machine may also attach directly under a site or area, a labeled exception, not the default, since a two-machine shop may never want areas, but an area’s parent must be a site and a work center’s parent must be an area, with no skipping: those are the layers routings and preferred-routing rates attach to later. Ids are always derived from the name (slugified, shown as a read-only hint) and can never be typed or left blank. Reads/writes go through the level-agnostic /nodes endpoints (GET /nodes/tree, POST /nodes/, PATCH /nodes/{id} for edits and re-parenting) instead of the older per-level /hierarchy/sites|areas|work-centers endpoints.

Machines and lines (folded into Plant Structure)

There’s no separate Assets page anymore, a machine or line is a node added directly in the Plant Structure hierarchy editor (/hierarchy, an “Add Machine” affordance under a work center or area), so raw telemetry tags map to something meaningful everywhere else in the app (Facility Map’s node boxes, Historian’s device picker, Maintenance’s queue) without a separate CRUD screen. Linking a machine’s telemetry tags happens on the Tags/Sources side, see Setup, edge and devices.

Shifts and schedules (Workforce)

A shift schedule defines named time windows (e.g. “Day 6a-2p,” “Night 10p-6a”) for a site, configured on the Shifts tab of Workforce (/shifts, alongside an Operators tab). Every shift-scoped number elsewhere in the app, Production’s per-shift counts, Shift Handoff’s comparison window, Reports’ shift-vs-shift chart, depends on this configuration being correct. Without it, those screens can’t know where one shift ends and the next begins. Schedules can be filtered by site, added one at a time via a form, or bulk-loaded via CSV upload (POST /shifts/upload-csv/{site_id}?schedule_name=...&effective_start_date=...). An empty tenant shows an explicit “No shift schedules found. Create one to get started!” message instead of a blank page.

Rates & Costing

Plant-wide labor and machine rate/cost inputs live on their own Rates & Costing page (/rates-costing). These feed every dollar-scoped surface elsewhere, job costing, the Opportunities board, Verified Savings, so a rate configured here is the one source those screens resolve through. See How to set plant rates and costing.

Users and roles (Admin nav group)

Three roles exist: admin (full tenant management), super_admin (everything admin has, plus the Operations console), and an implicit lower tier for anyone without those roles (read-mostly). The Users page (now /users in the Admin nav group, merged with a Groups tab) lets an admin bulk-add users (POST /users/bulk), remove a user, and trigger a password reset, all without going through support. Role gating is enforced both in the UI (nav items and mutating controls hidden) and on the server. See How to manage users and groups.

The Operations console (Admin nav group, super_admin, two-factor required)

Operations (/ops) is the one place every platform-staff screen lives: Tenants, Demo, Releases, System health, Errors, and Audit, on its own left rail. A super_admin without two-factor authentication set up sees only a two-factor enrollment screen here, nothing else, until they set it up, every other screen in the app is unaffected by this requirement.

Releases and signed edge-agent builds (Operations console, super_admin, two-factor required)

A release is a published, versioned edge-agent build, verified by an Ed25519 signature (sha256 + signature shown per row). This screen (/ops/releases, inside the Operations console) is read-only in the browser, registering a release is a CI-only action requiring the signing key, not something a super_admin does by clicking a button here. The point of this screen is verification: confirm every published build is signed before pinning a gateway to it on Gateways.

Tenants (Operations console, super_admin, two-factor required)

A tenant is a customer organization, Spall is multi-tenant, and a super_admin can create, view, and delete tenant organizations from this screen (/ops/tenants, inside the Operations console) instead of touching the database directly. Creating one walks through a short setup checklist: plan and limits, an optional invite for the new tenant’s admin, the data owner, a machine template link, and a referral partner. Deleting a tenant is destructive (removes the tenant and all associated users/data), so the confirm step requires typing the tenant’s ID exactly. The server also refuses the request for the tenant you’re currently signed in through, the demo tenant, or a tenant that still has an enrolled gateway (retire the gateway first).

The onboarding path

Getting Started is the front door for a brand-new, empty tenant: it tracks real status flags (has_sites, has_assets, has_gateways, has_shifts, has_data) against GET /api/v1/onboarding/status, checks each step off automatically the moment it becomes true, and links each step straight to the screen that completes it. “Build your plant hierarchy” and “Add your machines” both link to /hierarchy now, the same page builds the whole tree, site down to machine, so there’s no detour through the separate Assets screen just to finish onboarding. This is the same checklist the admin/integrator training path walks through step by step.

How the pieces relate

Plant Structure (hierarchy) and Workforce (shifts) are the two prerequisites the Getting Started checklist tracks before “See live OEE” can light up, they define where things are (down to the machine node) and when shifts run. Rates & Costing layers dollar figures on top once the tree and telemetry exist, and its own “Price your machines” checklist step follows right after live OEE, so a dollar figure never rests on the app default without anyone noticing. Users, Software/Releases, and Tenants are a separate access-and-fleet-governance cluster, now grouped under Admin instead of Setup, unrelated to plant modeling, scoped to admin/super_admin. See Setup, edge and devices for how gateways connect the physical floor to this hierarchy.