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](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](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](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.