Glossary
The vocabulary used across Helm. When a term is used in code, in this bible, or in operator UI copy, it should match this glossary.
Foundational terms
PSaaS — Precision Software-as-a-Service. Software that adapts to the shop instead of the shop adapting to the software. The category Helm sells in. See The Doctrine.
The Doctrine — Helm's foundational commitment: the software stops being something the shop buys and starts being something the shop owns, shaped by their hands over time. See foundation/doctrine.md.
Substrate — what's canonical in Helm: the data model, audit chain, regulatory layer, API contract, security boundary, identity model. Identical at every shop; only Kvick modifies it. See The Substrate Line.
Surface — what's open in Helm: workflows, UI, modules, reports, integrations, language. Free to drift per shop; drift here is the product.
The Substrate Line test — "Would a change here, made at one shop, become unsafe or incorrect if not made at every shop?" If yes → substrate (Kvick decides, propagate). If no → surface (the shop decides, ship).
The Customer Compact — what Kvick brings (substrate, AI build engine, days-not-quarters response, operational continuity, honest "no") vs what the shop brings (articulation, decisions, time for walkthroughs, trust in the Substrate Line). See foundation/customer-compact.md.
Helm-internal terms
Adapter — a thin wrapper around an external API (Stripe, Twilio, Claude). Lives in src/lib/{name}.js. Encapsulates auth, retries, idempotency keys for that vendor.
Audit chain — the hash-linked sequence of audit_events rows. Each row's chain_hash includes the previous row's; tampering breaks the chain forward.
Audit event — one high-level record of who did what to what entity when. Stored in audit_events.
Audit mutation — the row-level before/after snapshot accompanying an audit event. Stored in audit_mutations.
Bible — this documentation site. The canonical, version-controlled specification of how Helm works.
Bike on record — a customer's bike that the shop tracks. Lives in customer_bikes. Can be linked to service tickets.
Bundled with bike — a component sold alongside a new bike at point of sale, which qualifies the component for BC PST exemption.
Frequent tab — the operator-customizable tab on the Sales screen showing the SKUs the shop sells most often.
Helm — the bike-shop POS product (KVICK.BIKE Helm). The Worker app + the per-shop D1 + R2 + cron triggers.
helm-editable — the universal inline-edit chassis. Dashed-underline cue on hover; contenteditable on click for single-value cells, or a per-till modal for composite records. See helm-editable doctrine.
In-situ editing — direct manipulation of customizable elements from the screen they live on. Principle: in-situ editing. Chassis: helm-editable.
Kvick — the company. Singular vendor; corporate identity behind Helm.
Operator — anyone using the Helm POS — staff, mechanic, owner. Internal-facing user.
PIN — 5-digit staff sign-in code. Stored hashed via PBKDF2-SHA256.
Shop — one customer of Kvick. A bike shop with its own Helm deployment.
Shop config — the per-shop settings row(s) in the shop_config table.
Sign-in overlay — the lockout-only PIN entry screen that opens automatically on idle timeout.
Slice — one vertically-built feature: schema + API + UI + tests + docs. See slice overview.
Sys Admin — auto-created top-tier staff role. Has all permissions including direct sign-in via the admin reset code.
Today dashboard — the home screen for operators, showing the day's state (open tickets, today's sales, low-stock alerts).
Worker — a Cloudflare Worker; the runtime hosting Helm's app code. One Worker per shop.
Tax & financial terms (BC-specific)
GST — Goods and Services Tax, 5%, federal. Applied to almost everything.
PST — Provincial Sales Tax, 7% in BC. Applied to many goods and services with several exemptions.
Bike-bundle exemption — BC's rule that components sold bundled with a new bike are PST-exempt.
Idempotency key — the unique identifier sent with a write request that prevents double-execution under retry. Required on every external write — see ADR-0015.
Refund — money returned to a customer; typically tied to a transactions parent row and reduces the parent's net total.
Return — physical goods coming back; may or may not involve a refund (could be a warranty replacement).
Trade-in — a customer's used bike accepted as partial payment toward a new purchase. Becomes inventory.
Service-shop terms
Drop-off — when a customer leaves a bike with the shop for service. Creates a ticket in dropped_off status.
Picked up — when a customer collects a serviced bike and pays. Terminal status for a healthy ticket.
Kanban — the column-based service ticket board (Dropped Off / In Progress / Awaiting Parts / Ready / Picked Up).
Service menu — the configurable list of standard services (tune-up, brake bleed, wheel build) with default labor + parts allocations. Stored in service_categories.
Ticket line — one line on a service ticket. Either a labour line or a parts line.
Ticket lifecycle — the sequence of statuses a ticket passes through. See service-ticket lifecycle.
Inventory & purchasing terms
SKU — Stock-Keeping Unit. A distinct product item the shop tracks.
Variant — a sized or colored version of a SKU. Inventory is tracked per variant.
PO — Purchase Order. An outbound order to a vendor (QBP, Shimano).
Low-stock alert — the daily-cron-generated list of SKUs below their reorder threshold.
Vendor — a supplier (QBP, Shimano, Specialized, etc.). Each variant has a primary vendor.
Rental terms
Fleet — the shop's bookable rental bikes. Stored in rental_fleet.
Booking — a customer's reservation of a fleet bike for a date range.
Pickup — when the customer arrives to collect the booked bike; transitions to active.
Return — when the customer brings the bike back; transitions to returned.
See also
- Slice overview
- Entity reference — start with customer
- Lifecycles — state machines for the main entities