sims-hq/docs/11-ADMIN-SUPPORT-CONSOLE.md

11 — Admin, Settings & the HQ Support Console

Founder review question (2026-07-09): "how are the support sections, and are there admin pages/settings — default settings, multi-tenant settings, etc.?" Verdict: the tenant-side Admin module is specified in 09-UX-FLOWS-AND-MENUS.md (§2 menu tree → Admin; §5.7 error-code support handshake; print-profile remote fixes in §5.4). What was missing is the vendor side — the console our team and dealers use to run the whole fleet. This doc fills that gap and consolidates the settings model.

⚡ Staging update (founder call, 2026-07-09 — see D15)

The commercial slice of this console is built early as apps/hq, aimed at the current Classic client base: tenant/client directory, Billing & Collections, notes/history — spec: 14-SPEC-HQ-CONSOLE.md, which adds quotations/proforma, AMC, AWS cost attribution and the interaction log beyond this doc. Fleet/support/catalog features keep the §5 phase mapping and still wait for the cloud tier (D14).

1. The five surfaces (corrected count)

Surface	Who	Where specified
POS Counter	store staff	09 §1
Back Office web	tenant's managers	09 §2
Owner App	tenant's owner	09 §4
Customer Display	the queue	09 §1
HQ Console (internal web) + dealer portal view	SiMS staff, dealers	this doc

2. The settings model (one mechanism, five scopes)

Every setting is a row: setting(scope_type, scope_id, key, value, effective_from). Resolution: nearest scope wins — user → counter → store → tenant → system.

Scope	Edited from	Examples
system (= SiMS default)	HQ Console → Catalogs → Default Settings	default rounding rule, default print routing, default alert thresholds, IRN retry window, grace-period days
tenant	Back office → Admin → Settings	GST scheme (regular/composite), FY start, invoice formats, dealer-first support routing, languages enabled
store	Back office → Admin → Stores	store print language, negative-stock policy, khata limits default
counter	Back office or POS Settings (supervisor)	print profiles, approval timeout, quick-keys layout, font size
user	The user (POS/app settings)	language, notification preferences, muted alert types

Rules: every override shows what it inherits ("Inherited from Store: ₹500 — Override?") with one-click reset to inherited; changes are effective-dated and audit-logged; a "changed from default" filter exists at every scope — support's first question answered in one click. New-tenant provisioning = the system scope snapshot + edition template; that's what "default settings" means operationally.

3. HQ Console — menu tree

Internal web app on the cloud tier (never store-installed). Staff roles: Support Agent, Support Lead, Product Admin, Finance, Read-only Auditor. Every staff action touching tenant data is itself audit-logged — we are tenants of our own audit system.

• 🏬 Tenants
  • Directory: search, filters (edition, region, dealer, version, sync health, renewal due).
  • Tenant 360°: stores/counters/devices with app versions, sync lag, last backup, subscription state, usage stats (bills/day), open error-code counts, notes/history.
  • Lifecycle: provision (from edition template), suspend (grace rules), archive/export (DPDP-compliant handover), delete with legal-hold checks.
  • Migration tracker: Classic→Next pipeline per customer (scheduled → data pulled → verified → parallel-run → cut over → Classic retired), verification-report status.
• 💳 Plans & Pricing (Product Admin only)
  • Plan editor (plan, plan_feature matrix — feature flags as rows).
  • price_book with effective dates (D5: prices are data; changing them is a row, not a release).
  • Offers: migration discounts, dealer pricing, renewal offers.
  • Upsell content editor: the in-app paywall screenshots/text per feature (DB-driven marketing).
• 📚 Catalogs (pushed to fleet via sync)
  • message_catalog editor with translation workflow (missing-strings report, machine-draft → human-confirm per language).
  • error_catalog editor incl. the internal support_note playbook per code.
  • GST rate catalog: dated rate pushes (the GST-2.0-style event = one dated dataset push).
  • HSN reference data; default print/label template gallery.
  • Default Settings (the system scope — §2).
• 🚀 Fleet
  • Version dashboard: which store runs what; rollout rings (internal → pilot stores → dealer wave → all) with halt/rollback; version pinning per tenant when needed.
  • Sync health map: red/amber stores (lag, backlog size, last error), drill to op log.
  • Telemetry explorer: error-code frequencies (E-xxxx as the currency of support), per-bill timing percentiles by store — the "fastest counter" SLA, watched live.
• 🛟 Support
  • Queue/board (or ticket-system integration — decide in D13): tickets carry tenant + error codes automatically from the diagnostic bundle.
  • Store 360° (same as tenant view, scoped to one store) with remote actions: pull logs, push config fix (e.g., print profile), re-pair a reinstalled POS, refresh license token, trigger backup, queue a test print.
  • Impersonation ("view as tenant back office"): requires owner consent (OTP/WhatsApp approve), is time-boxed, watermarked on screen, fully audit-logged, and never covers POS.
  • Backup/restore console with restore-drill tracking per store (the drill is a checklist item, not a hope).
• 🤝 Dealers
  • Directory, territories, their customer lists, commission statements.
  • Dealer portal (restricted HQ view): only their tenants; onboarding wizard launch, migration tracker, first-line support tools (no impersonation, no catalogs, no pricing).
  • Kit management: install packages, keyboard sticker sheets, training scripts.
• 💰 Billing & Collections (Finance)
  • Our own GST-compliant subscription invoices to tenants; renewals-due pipeline; dunning sequences (WhatsApp/email, from message_catalog); dealer commission runs.
• ⚙️ Internal Admin
  • Staff users/roles, staff-action audit browser, GSP/WhatsApp/UPI credential vault (rotation dates), environment health.

4. Support flow, end to end (shop → HQ)

1. In-app: error rail shows E-2101 + plain-language fix; if unresolved, "Get help" sends a diagnostic bundle (app version, device profile, last 50 error events, sync status, anonymized — never bill contents) and shows the tenant's support route.
2. Routing (tenant setting): dealer-first (default — the dealer relationship is the channel) or direct-to-SiMS; WhatsApp support number deep-link with the error code pre-filled — the shop's preferred medium.
3. HQ: ticket lands with tenant/store/code attached; agent opens Store 360°, uses remote actions; escalation to impersonation only with consent; the support_note playbook per error code is the agent's first screen.
4. Loop closed: resolution tagged per error code → weekly top-codes review feeds the backlog (a code that spikes is a product bug, not a support workload).

5. Phase mapping

Phase	HQ Console scope
1 (MVP)	Tenant provisioning + lifecycle, license/plan assignment, fleet version dashboard + rollback, Store 360° with log pull + config push, migration tracker, system-scope defaults, staff roles + audit
2	Full catalogs editing (messages/errors/GST pushes), sync health map, rollout rings, billing & dunning (moved early → HQ-1/HQ-2, see staging note and 14-SPEC-HQ-CONSOLE.md), support queue
3	Dealer portal, impersonation (with consent flow), telemetry explorer, upsell content editor, commission runs
4	Restore-drill automation, advanced fleet analytics, API/partner management

6. New decision raised

D13 — Support ticketing: build the queue in HQ or integrate an existing helpdesk? Recommendation: integrate something boring in Phase 2 (the diagnostic bundle and Store 360° are ours; the ticket list is commodity), revisit building only if the integration fights the error-code workflow.