Skip to main content

Roadmap

Helm is built to be the operating system for a bike shop, not just the till. Beyond the current 11 slices (see slice overview), fifteen additional capabilities have been identified for v1+. Each will be built as its own slice or as augmentation to an existing slice/ADR, following the slice-development pattern.

Drafted from planning · v0.1

This page is the canonical home for the planned-but-not-yet-built roadmap. Project files and session handoffs reference it; they do not duplicate it. Reordering and additions happen by editing this page. Dropping a feature moves it to the Deferred section with a rationale — never silently.

The list is ordered for build sequence, not calendar dates. Each stage unlocks a meaningful business capability; finishing a stage is the natural place to pause, verify, and decide whether to keep going.

Stages at a glance​

StageCapability after this stageFeatures
1 — FoundationsIn flight; not on this page(see current state)
2 — Complete the tillHelm replaces AIM at Swicked12, 13, 14
3 — The bike-vertical primitiveBike-specific differentiation lands15, 16, 17
4 — Back-of-shop completenessHelm runs the whole back office18, 19
5 — Growth and reputationLoops that grow each shop's revenue20, 21, 22
6 — Community and intelligenceThe shop becomes a hub, not just a store23, 24, 25
7 — Chain capabilityMulti-location for any shop that growsFederated (ADR + slice updates)

Stage 1 (Foundations) is the in-flight work — OAuth+PIN auth, build versioning, focus stewardship, idempotency keys, the Sales (Ring-Up) slice, the offline cache layer. Those are tracked in current state and the project's session handoff, not duplicated here.

Architectural pin — before Stage 3​

Three of the new features (15, 16, 17) all depend on the same underlying concept: a serial number treated as a first-class entity with its own lifecycle, not just a text column on an inventory row. The primitive must land before any of the three features build.

See ADR-0024: Serial numbers as first-class entities.

Stage 2 — Complete the till​

After Stage 2, Helm is operationally complete enough to fully replace AIM at Swicked Cycles. This is the moment Swicked becomes a real production deployment, not a parallel system.

Slice 12 — Cash drawer sessions​

What it is. A "session" wraps every interval the drawer is open under one staff member. Open-drawer → ring sales / refunds / pay-outs → close-drawer with cash count. Variance between expected and counted is logged, audited, and reported.

Why. Cash handling is the highest-trust, lowest-tech-supervised activity in a bike shop. Without sessions, every shift's cash is one undifferentiated pile and accountability dissolves. Sessions make cash variance visible and assignable.

Dependencies. Slice 1 (audit), slice 5 (transactions). No new external dependencies.

Status. Spec pending.

Slice 13 — Returns and exchanges​

What it is. First-class return workflow tied to an original transaction. Partial or full, with or without restocking, with or without exchange. Handles tax recomputation, inventory adjustments, and refund-method-matches-original logic. Same screen handles "no receipt" returns with manager override and a different audit trail.

Why. Returns are inevitable in retail. Today Slice 5 has a refund path; that's not the same as a return — refunds are money-only, returns are money + inventory + sometimes new merchandise. Without a proper workflow, returns become manual reconciliation work.

Dependencies. Slice 5 (transactions), slice 3 (inventory). Stripe Terminal refund flow.

Status. Spec pending.

Slice 14 — Gift cards and store credit​

What it is. Issued at point-of-sale or as part of a return. Tracked as a liability balance against a code (gift card) or against a customer (store credit). Redeemable as a tender method during sale. Expiration rules per BC law. Audit trail for every load and redemption.

Why. Gift cards drive holiday revenue; store credit closes the return loop without giving cash. Both are common in the AIM data being migrated; not having them in Helm at cutover means manual workarounds for known patterns.

Dependencies. Slice 5 (transactions), slice 13 (returns — store credit issuance most often happens there).

Status. Spec pending.

Stage 3 — The bike-vertical primitive​

Three features that share one underlying primitive (per ADR-0024). Build the primitive first; the three features then compose on top.

Slice 15 — E-bike serialization and battery lifecycle​

What it is. First-class tracking for serialized objects with their own lifecycles: bikes by frame serial, batteries by battery serial, motors by motor serial. Battery-specific attributes (cycle count, charge history, firmware version, warranty period independent of the bike) live on the battery row, not the bike row. A bike can have multiple battery records over its lifetime; relationships are tracked.

Why. E-bikes are the highest-margin, fastest-growing segment of the bike industry, and they're also where the warranty / recall / firmware-update workload concentrates. Tracking the battery as a separate object (rather than a text field on the bike) is what makes that workload tractable.

Dependencies. ADR-0024 — must land first. Slice 2 (customers) and slice 3 (inventory).

Status. Spec pending.

Slice 16 — Bike registration integration​

What it is. Push-button registration with Project529 (Canada/BC primary) and Bike Index (international). At sale or at drop-off, the operator clicks Register → Helm posts the bike's serial, photos, and owner consent to the registry. Registration ID stored back on the serialized object record.

Why. Theft is the largest single complaint from bike shop customers, and registration is the single most effective recovery tool. Bike shops are the natural moment to register a bike — already capturing serial, photos, owner — but today nobody does it because it's a friction. One button removes the friction.

Dependencies. ADR-0024, slice 15 (serialized object schema in place). Project529 API credentials, Bike Index API credentials.

Status. Spec pending.

Slice 17 — Warranty claim workflow​

What it is. From "customer reports an issue covered by warranty" → vendor claim packet (photos, serial, original purchase record, failure description) → claim status tracking → resolution (replacement / credit / repair). Per-vendor templates because every vendor's claim format is different. RMA numbers tracked; replacement bikes/parts flow into inventory with a "warranty replacement" cost basis.

Why. Warranty claims today are a multi-hour-per-claim manual process — find the purchase record, copy serial, take photos, fill out the vendor's form, email, follow up. A shop running a high volume of e-bikes accumulates 5–10 of these per month. Automating the data assembly turns a half-day task into a 15-minute one.

Dependencies. ADR-0024, slice 15 (serialized objects), slice 4 (service tickets — warranty claims often start as service tickets), slice 6 (POs — replacement parts come in as POs with a different cost basis).

Status. Spec pending.

Stage 4 — Back-of-shop completeness​

After Stage 4, Helm runs the whole back office, not just the front.

Slice 18 — Bookkeeping bridge (QuickBooks Online integration)​

What it is. Daily push of summary journals to the shop's QuickBooks Online account: sales-by-tax-category, payments-by-method, refunds, gift-card liability change, inventory cost-of-goods. Per-shop QBO credentials via OAuth. Reconcilable from QBO back to Helm via day-stamped journal IDs.

Why. Every shop pays an accountant or bookkeeper. Today the bridge is manual CSV export → manual import. Automating the daily push removes ~2 hours/week of repetitive manual work for the shop and makes the accountant's reconciliation trivial.

Dependencies. Slice 5 (transactions), slice 14 (gift cards — liability tracking), slice 3 (inventory — COGS). QuickBooks Online API + OAuth.

Status. Spec pending.

Slice 19 — Clock-in/out and labor tracking​

What it is. Staff clock in/out from the operator UI. Hours roll up per pay period. Labor cost rolls into service-ticket profitability reports (cost = parts + labor hours × wage). No payroll calc (out of scope; payroll stays at the shop's payroll vendor) — Helm tracks hours, the vendor processes pay.

Why. Today the shop has no labor data tied to its service revenue, so unprofitable categories are invisible. Tracking hours unlocks cost-of-service reports, which inform pricing and capacity decisions. Also: the labor record lives next to the work it was for, which makes accountability and disputes trivial.

Dependencies. Slice 1 (staff records, audit), slice 4 (service tickets — labor links to ticket lines).

Status. Spec pending.

Stage 5 — Growth and reputation​

Loops that grow each shop's revenue without growing its operator workload.

Slice 20 — Reviews automation​

What it is. Post-service-pickup SMS or email: "Your bike's done. How'd we do?" with a one-tap link to Google Business Profile / Bike Index / shop's own review surface. Customer's reply is recorded back to Helm and tied to the ticket. Operator sees a digest of reviews per week.

Why. Reviews drive bike-shop foot traffic more than any other marketing investment, and they're free to ask for. Most shops don't ask consistently because it's manual. Automating the prompt at the moment of greatest satisfaction (just got my bike back working) captures reviews systematically.

Dependencies. Slice 4 (service tickets), slice 10 (Twilio for SMS). GBP API (already in C4 context). Per-customer marketing opt-in (slice 2).

Status. Spec pending.

Slice 21 — Marketing automation tied to bike and service data​

What it is. Segments built on bike-shop-specific signals: "owns an e-bike, last service > 6 months" → reminder; "bought a kid's bike 2 years ago" → upgrade suggestion; "owns a Specialized" → new-Specialized-arrived blast. Sends through Twilio (SMS) and email. Segment definitions are saved and editable in-situ per in-situ editing.

Why. The existing marketing slice (10) handles channels. This adds the segments that bike shops actually need but generic CRMs don't ship with. Bike-vertical signals (service-due, model-upgrade, brand affinity) are the differentiator.

Dependencies. Slice 10 (marketing infrastructure), slice 2 (customers), slice 4 (service history), slice 15 (serialized objects for e-bike specific segments).

Status. Spec pending.

Slice 22 — Trade-in valuation tooling​

What it is. Operator scans or types the bike being traded in; Helm pulls comparable recent sales (locally and from connected price-data sources), suggests a fair trade-in offer, records the customer's bike against the new serialized-object entity, and flows the trade value as credit toward the new purchase. Built on top of existing slice 8 (Trade-In).

Why. Trade-in pricing today is the operator's gut feel, which means either leaving margin on the table or losing the customer's trust. Data-backed valuation gives the operator a defensible number in seconds.

Dependencies. Slice 8 (trade-in workflow), ADR-0024, slice 3 (inventory). Optional: external price-data API.

Status. Spec pending.

Stage 6 — Community and intelligence​

The shop becomes a hub, not just a store.

Slice 23 — Events and group rides module​

What it is. Schedule shop-led group rides, demo events, race team meetups. Customers RSVP from the public site or are added by the operator. Attendance is recorded and rolls into the customer's profile (frequent-rider segment for marketing). Photos/recap attach to the event.

Why. Group rides and events are the single largest community-building lever for an independent bike shop. Today they live in Facebook events and a shop email list. Bringing them into Helm makes the attendance signal first-party data, usable by Stage 5 marketing.

Dependencies. Slice 2 (customers), slice 10 (marketing for RSVP nudges), slice 20 (reviews — events generate review opportunities). Public-site touchpoint.

Status. Spec pending.

Slice 24 — Vendor performance scorecards​

What it is. Per-vendor metrics surfaced in Helm: fill rate on POs, return rate on units sold, warranty-claim rate by SKU, average lead time, price-change frequency. Owner sees the scorecard when reviewing POs or considering line additions.

Why. Today vendor decisions are anecdotal — "Specialized has been good lately" — which means underperforming vendors stay on the shelf longer than they should. The scorecard turns vendor performance into a number, which makes line cuts and additions a normal periodic decision.

Dependencies. Slice 3 (inventory + vendors), slice 6 (POs), slice 13 (returns), slice 17 (warranty claims). All data already exists; the slice is reporting + UI.

Status. Spec pending.

Slice 25 — Per-shop wiki​

What it is. A small Markdown-based knowledge base inside the shop's Helm deployment. SOPs, vendor contact notes, how-tos for the quirky bits of the local shop. Editable in-situ per in-situ editing. Owner can mark sections as customer-facing for the public site.

Why. Every shop accumulates institutional knowledge that today lives in the owner's head or in a Google Doc nobody reads. A wiki inside Helm — surfaced where the relevant tickets/transactions/customers live — turns that knowledge into a daily-use asset.

Dependencies. Slice 1 (auth/audit). Optional: linking from other screens to wiki entries.

Status. Spec pending.

Stage 7 — Chain capability​

Federated multi-location​

Implemented as an ADR plus updates to existing slices, not as its own numbered slice. The decision is captured in ADR-0025: Federated multi-location. Summary:

  • Each location is its own Helm deployment with its own D1, preserving single-tenant per shop and ADR-0003
  • A chain_memberships record links locations into a chain
  • A federated reporting layer fans out queries across member deployments
  • Inventory transfers between locations are a special transaction type that posts on both ends
  • Customer records can be opt-in shared across chain members

Affected existing slices. Slice 3 (inventory transfers between locations), slice 5 (transactions tagged with location for chain-level reports), slice 6 (POs may be chain-wide), slice 19 (clock-in across locations for one chain employee).

Dependencies. Most of stages 2–6 in place before this is operationally interesting.

Status. ADR accepted; implementation spec pending.

Dev tooling follow-ups​

Not roadmap-level capabilities — operational items tied to the System Flow Map dev tool (devtools/flow-map), tracked here so they don't get forgotten when the temporary mount in Helm is removed.

  • Point graph.json at the real extractor output once it exists. The viewer currently serves graph.sample.json (a hand-laid seed graph) when no real graph.json is present. A future extractor task walks src/index.js + public/index.html and emits a real graph.json matching the documented contract. When that lands, the route in src/devtools/flow-map/route.js already prefers graph.json over the sample — no viewer change needed.
  • Move the flow map from its temporary Helm mount to its permanent home. The tool is wired in as a guest — removable by deleting two reference lines plus the src/devtools/flow-map/ and public/devtools/flow-map/ folders. When the permanent home is decided, follow the removability checklist in devtools/flow-map.

Deferred​

Features that get reconsidered and dropped move here with a note explaining the reasoning. Nothing today.

Discipline​

New features beyond this list require explicit consideration of whether they belong on the roadmap before being built. Scope creep produces a conscious decision (an entry added here, with a rationale) rather than silent expansion of in-flight work.

A useful check before any non-roadmap work begins:

  1. Is this feature already on the roadmap? If yes, build it in stage order — don't pull it forward without a reason.
  2. If it's not on the roadmap, would adding it displace something that is? If yes, this is a re-prioritization decision; surface it explicitly.
  3. If it's adjacent enhancement to a built slice (small, scoped, doesn't change architecture), it doesn't need to be on the roadmap. The roadmap is for substantial new capability.

See also​