Appearance
Operating model: how the card becomes the operational spine
Part of
car_sales— the dealership operating layer. Decisions are in product decisions; this page is how they work.
1 · The unit of the system is a person, not a record
Every other dealership system is organised around a transaction (the deal, the job card, the invoice). This one is organised around a person with a card. That single change is what makes attribution possible, and it is why the hierarchy, the follow-up SLA and the performance view all fall out of one model instead of needing three.
Organisation (the dealer group)
└── Showroom ← OWNS customers, visitors, vehicles (ADR-0024 D2)
├── Sales division
│ ├── Sales Manager card
│ ├── Team Leader card
│ └── Sales Rep card ← the customer-facing edge
└── Service division
├── Service Manager card
└── Advisor card🧮 This shape is already built and proven. organizations exists with five sharing flags, workspaces is a real tree with a materialized path and depth capped at 6, three RLS helpers are wired into live policies, and the pgTAP suite proves the negatives against a fixture named Kalyani Motors with Thane and Andheri showrooms and agents Ravi and Sneha. 📘 ADR-0024 was derived from these workflows.
2 · The ownership decision, and it is the one that can kill the product
🌐 Frontline attrition is 29.53%, with an actuarial assumption of 25% a year for under-35s — exactly the sales-executive cohort
So roughly one rep in four leaves every year. If the card and its customers belong to the rep, then a quarter of the dealership's customer relationships walk out annually, carried in a tool the dealership paid for. That is not a moat; it is a customer-export feature.
The resolution, and the mechanism already exists:
| Question | Answer | Mechanism |
|---|---|---|
| Who owns the rep's card? | The organisation | 📘 workspaces.ownership_model = 'org_owned' |
| Who owns the customer? | The showroom, one level up from Sales and Service | 📘 ADR-0024 D2 — which also makes the sales↔service join structural rather than a report |
| What does the rep get? | Identity and credit. Their name, face, designation on the card; every interaction attributed to them; their performance record | attribution on the event |
| What happens when they leave? | The card is reassigned or retired; leads and parties stay with the showroom; the performance history stays as the dealership's record | role reassignment |
| What must the employer never see? | 📘 The rep's own member_owned workspaces — a personal side business, a consumer identity | 📘 ADR-0024 D1 + QRS-386: oversight applies only to org_owned descendants |
🔎 Say this explicitly in the sales conversation. "Your reps get the identity, you keep the customers" is the sentence that makes a Dealer Principal comfortable, and it is exactly the anxiety a per-employee card raises first.
3 · What an interaction event must carry
🔎 Get this wrong and no rollup above it is trustworthy. Every event needs five dimensions, and the attribution dimension is the one no other system has.
| Dimension | Example | Why |
|---|---|---|
| Who shared it | card_id → employee → workspace path | The attribution. Without it this is web analytics |
| What was viewed | catalogue item, offer, block | Vehicle-level interest, which drives the follow-up |
| What action | open · view · tap · enquiry · test drive · callback · feedback | The funnel |
| When | timestamp | Aging and SLA |
| Who the visitor is | phone if given, else anonymous | 📘 Anonymous-first. A card must work with no account |
Two constraints on this that are easy to miss
- 📘 Counts, not profiles. ADR-0010 D7 decided counts-only, and it should hold. A per-visitor behavioural profile brings DPDP profiling duties and buys nothing the dealer needs.
- 📘 Purge-on-write, never TTL. ADR-0027 governs card freshness. A live offer or price on a card is a cache-invalidation event, not a short expiry.
4 · The hierarchy is oversight, and it is read-only
📘 ADR-0024 D1: resource sharing flows DOWN, oversight flows UP, and they are never symmetric.
| Direction | Rule | |
|---|---|---|
| Sharing | parent → child | A child may use an ancestor's resources. Default off |
| Oversight | child → ancestor | An ancestor role may read descendants' operational data. Never write |
So the Team Leader dashboard is not a new feature and not a copy of the data. It is the same rows read with a subtree-scoped role. A lead created on Ravi's card is one row, owned by Ravi, read at three levels. 📘 No duplication, no sync, no "also flows into" write — which is the duplicate-source-of-truth class (QRS-249) avoided by construction.
⚠ A rep must not see a sibling rep's leads. 📘 pgTAP must prove that negative, along with: oversight cannot write; a manager cannot read a descendant's member_owned workspace; Thane cannot see Andheri at any depth.
5 · The journey, end to end
🔎 Note where the walk-in enters. The visitor register feeds the same lead spine as the card, which is why it is cheap to build and why it doubles the captured volume: a card only sees customers a rep chose to send it to, while reception sees everyone who walks in.
6 · The visitor register, and why it ships first
| Property | Value |
|---|---|
| Who uses it | The receptionist, every day, all day |
| What it replaces | 🌐 A physical notebook |
| What it needs | parties + a task. No attribution model, no hierarchy, no OEM data, no card |
| What it produces | The lead spine's highest-volume input, plus the first honest walk-in count the dealership has ever had |
| Why it is strategic | 🔎 It is the only capability here that creates a daily habit for a non-sales employee. Adoption failure in this product looks like reps not opening the app; reception has no such option, because the notebook is their job |
7 · Follow-up is the accountability surface
The value is not the task list. It is the two questions a manager cannot answer today:
- Who is not following up? Per rep: pending, overdue, average time to first contact.
- Where are leads being lost? Per stage and per reason, across the team.
🔎 That is why follow-up must carry an SLA and an overdue state, not merely a due date. A due date produces a list; an SLA produces a conversation.
8 · The WhatsApp fork, and it must be decided before the first customer
⚠ REFRAMED 2026-08-23 — this section decides who OWNS the WhatsApp account, and that is now a secondary question
📘 D7: QR Setu native chat is the system of record. WhatsApp is a reach and notification channel. 🌐 The Cloud API can only read messages sent to a business number we control, so a sales rep's own WhatsApp is permanently inaccessible — and pushing customers onto a business number is a customer-side behaviour change, which is the failure mode this vertical's roadmap is ordered around.
The fork below still matters — we still send utility messages, reminders and campaigns, and Option A versus C still decides branding and credits. What changed is that it no longer decides where the conversation lives. Full analysis: AI strategy §4a.
📘 ADR-0029 sets Meta Cloud API direct. 📘 ADR-0030 decides tenant identity, and its constraints make the owner's "recharge" model a genuine fork rather than a preference.
| A · QRSETU's account sends | B · Dealer owns the account | C · Solution Partner | |
|---|---|---|---|
| Meta bills | QRSETU | The dealer | QRSETU |
| Can you sell recharges? | Yes | No | Yes |
| Dealer-branded sender | No — dealer name rides in the message body | Yes, verified | Yes |
| Isolation | ⚠ None. Limits pool per portfolio, so one dealer's campaign can throttle everyone | Full | Full |
| Availability | Today | Today, self-serve | 🌐 "A lengthy process", no published criteria, irreversible once attached |
Recommendation
Start on A, and price recharges on it. Operational messages — enquiry acknowledgement, test-drive confirm and remind, feedback, service due, insurance renewal — are 🌐 utility category at ₹0.1150, cheap, high-value, and the dealer's name in the message body is sufficient for them.
⚠ Then the non-deferrable item: because limits pool per portfolio, a per-workspace send cap must exist before the first campaign runs. 📘 feature_grants.limit_value and on_exceed already support it.
Hold C until a named dealer refuses to proceed without a verified sender. Do not pursue it speculatively — and do not onboard dealers onto B first, because converting B → C means recreating every account and forfeiting its quality history.
⚠ This recommendation was briefly overruled to Option B on 2026-08-23 and then restored, because the migration-path argument in this very paragraph is decisive and the counter-argument (dealer branding is the product) applies to marketing messages while Wave 1-2 sends utility. See commercial model and QRS-848.
⚠ 🌐 And there is no margin in the messages themselves. Meta grants volume discounts on utility and authentication only, never marketing, pooled per portfolio. Price the service deliberately; do not plan on a wholesale spread that does not exist.
9 · What each layer needs, measured
🧮 Against the live migration set, 2026-08-22.
| Layer | Needs | Status |
|---|---|---|
| Card identity (B1) | setu_cards per workspace, org_owned | 🟢 built |
| Tree + oversight (B4) | organizations, workspaces tree, RLS helpers | 🟢 built and pgTAP-proven |
| Attribution (B2) | working beacon + analytics_events | 🔴 beacon broken (QRS-734), no events table |
| Customers (B3, B6) | parties | 🔴 not built |
| Leads (B3) | leads | 🔴 not built |
| Roles (B4) | roles, permissions, role_assignments, is_admin() | 🔴 0% built |
| Follow-up, test drives (B5, B8) | schedule, resource | 🔴 not built |
| Targets (B10) | targets over the analytics layer | 🔴 not built |
| WhatsApp (§8) | communication_*, a dispatcher, an outbox drain, a scheduler | 🔴 ADRs only. 🧮 Zero cron.schedule calls; nothing drains the outbox |
| Images on cards | a public media base URL | 🔴 fails closed; nothing calls setPublicMediaBaseUrl() |
| Org provisioning | a write path to organizations | 🔴 🧮 the only INSERT in the repo is the pgTAP fixture |
| Billing | org-level subscription | 🔴 🧮 workspace_subscriptions is keyed on workspace_id, so it is inexpressible |
Read that table as the schedule, not as a punch list
🧮 The substrate is genuinely done and it is the hardest part. Everything above it is not, and on this repo's measured velocity that consumes most of a twelve-month window — which is why go to market sequences six weeks of validation ahead of it, and why the first release is deliberately the subset that needs the least: beacon + parties + visitor register + card attribution.
Related
- Product decisions — what is in and out, and why
- Commercial model — the annual package book, cost to serve, and the WhatsApp decision
- 📘 ADR-0024 — D1 oversight, D2 customer placement, D3 asset