N NUKKAD Mohalla UI WIREFRAMES v1.0
Index Personas Customer Shopkeeper Saathi Central Ops Architecture APIs Data
UI Wireframes & mockups · Companion to tech spec v1.0

The screens and flows your team will build.

Ten annotated wireframes covering every persona, every critical flow, the system architecture, the data model, and the end-to-end API sequence. Designed to be read alongside the NUKKAD Mohalla Technical Specification.
Authored by
Vamsi Udayagiri · April 2026
Format
Schematic wireframes · not pixel-final
Scope
v1.0 MVP · urban Mohalla only
See also
NUKKAD_Urban_App.html · interactive prototype
Navigate

Ten wireframes.

Each wireframe captures a key flow or architectural view. They are schematic — true visual design lives in the interactive prototype. But every screen here maps directly to a section of the Technical Specification.
WF 01

Customer WhatsApp flow

Priya's query lifecycle from first message to handoff, including Turant and multi-shop scenarios.
WF 02

Shopkeeper WhatsApp flow

Ramesh receives lead, bids, wins, gets customer details — all within 45 seconds of a single message.
WF 03

Saathi dashboard

Rithika's daily view: KPIs, live queries, flags, onboarding queue, earnings. PWA, offline-capable.
WF 04

Shop onboarding pipeline

5-step pipeline from discover to activate. Per-step timing, state transitions, success criteria.
WF 05

Central Ops grid

Multi-Mohalla management view. Status chips, real-time KPIs, Saathi assignments.
WF 06

System architecture

5-layer architecture with canonical request flow. Surface → Intelligence → Orchestration → Data → Infra.
WF 07

Data model

14 core entities: mohallas, users, shops, queries, leads, broadcasts, subscriptions, flags, events.
WF 08

Customer journey

Priya from discover to advocate. 4 phases, 11 stages, emotion curve, per-phase KPIs.
WF 09

API sequence diagram

End-to-end query flow. 7 services, 12 calls, 4.4 seconds elapsed. What every engineer should know.
WF 10

Login + Auth flow

OTP-based WhatsApp login. 8-step flow. JWT sessions. RBAC across Saathi / Ops Lead / Central.
The four humans in the loop

Four personas.

Every feature in the spec scopes to one of these four. Keep them in mind as you scroll through the wireframes.
PM

Priya M

CUSTOMER · 34 · SAINIKPURI
IT professional, lives in Sunrise Residency Flat 302. Refuses to install apps for single-use needs. Heavy WhatsApp user.
Surface WhatsApp only. No app, no web.
RK

Ramesh K

SHOPKEEPER · 42 · SAINIKPURI
14 years running Sainikpuri Hardware. Electricals, plumbing. One employee. Wants customers without commissions.
Surface WhatsApp. Two-tap replies.
RD

Rithika D

NAGAR SAATHI · 28 · SAINIKPURI
Lives in Sainikpuri 6 years. Knows every RWA admin, every shop owner by name. Earns ₹22–28K/mo.
Surface Web dashboard (PWA) + WhatsApp.
HN

Hema N + team

CENTRAL OPS · HYDERABAD HQ
Head of Ops + 3 Regional Ops Leads. Multi-Mohalla strategic view. System health. Campaigns.
Surface Desktop web dashboard + Grafana.
Wireframe 01 · Customer flow

The customer never leaves WhatsApp.

Every customer interaction is a WhatsApp conversation. No app install. No login. No catalog. The entire experience — query, response, handoff, rating — happens inside a single chat thread.
Customer WhatsApp flow wireframe
FIG 01 · Customer WhatsApp flow · basic query to shop handoff

What this flow covers

  • 1
    Query. Free-text or voice. Claude parses intent in 600ms median.
  • 2
    Parallel broadcast. Top-N shops pinged. First to respond wins the race.
  • 3
    Handoff. Customer receives shop name, price, ETA, distance, call + directions CTAs.
  • 4
    Delivery loop. Customer shares address if delivery needed. Shopkeeper direct contact.
  • 5
    Rating ping. 90 min later. Single-tap thumbs up/down. Feeds ranking algorithm.

Technical surface

Meta Cloud API Templates (7) Claude Sonnet 4.5 PostgreSQL + PostGIS Redis (race lock)
SLO · intent to handoff

Median 6.4 seconds. p99 10 seconds. This is the tightest SLO in the system. Everything else can be slow; this cannot.

Wireframe 02 · Shopkeeper flow

The shopkeeper never installs anything either.

Same WhatsApp-only principle. Every shopkeeper interaction — lead receipt, bidding, win confirmation, monthly statement — is a template message with 2-tap replies.
Shopkeeper WhatsApp flow wireframe
FIG 02 · Shopkeeper flow · lead arrival, bid, win confirmation

What this flow covers

  • 1
    Onboarding. Saathi visits in person. One-tap consent via WhatsApp starts the 30-day trial.
  • 2
    Receive lead. Template message with item, distance, urgency. Reply YES [price] or SKIP.
  • 3
    Race. First valid response wins the lead. Others lose gracefully.
  • 4
    Win. Customer phone + address shared. Tap-to-call CTA.
  • 5
    Daily digest. 3pm summary: leads won/skipped, avg response time, GMV.
  • 6
    Monthly statement. 1st of each month, 11am. Renewal prompt, autopay CTA.

Response time SLAs

Standard lead · 180 sec Turant · 60 sec Digest dispatch · 3pm daily Statement · 1st @ 11am
Wireframe 03 · Saathi dashboard

Rithika's operating system.

The Nagar Saathi dashboard is a PWA. Desktop-first layout but mobile-responsive (most Saathis work from their phone 60% of the day). Critical paths work offline for up to 2 hours.
Saathi dashboard wireframe
FIG 03 · Nagar Saathi dashboard · main view · KPIs, live query stream, earnings, flags

Layout sections

  • 1
    Top bar. Role switcher (Saathi / Customer / Shop / Ops demos), user chip, live ticker with query count.
  • 2
    KPI band. 5 cards: Active shops, Retention 30d, Queries today, Contribution/mo, Open flags. WebSocket-driven, updates every 10 sec.
  • 3
    Live query stream. All queries in the Mohalla as they arrive. Status chips (LIVE / TURANT / OPEN / CLOSED). Click any row for full intent trace.
  • 4
    Earnings panel. Monthly breakdown: base + onboarding bonus + retention bonus + CSAT bonus. Locked on 25th.
  • 5
    Flags. Disputes, low-response warnings, star-shop callouts. Color-coded severity.

Technical requirements

  • •
    PWA. Installs to home screen. Service worker caches last 100 queries + shop graph.
  • •
    WebSocket. Real-time stream for queries and KPI updates. Reconnects on network drops.
  • •
    Offline mode. Read-only for up to 2 hours. Cached shop data, recent queries.
  • •
    Target page load. p50 1s, p99 3s. Next.js SSR + route-level code splitting.
  • •
    Design tokens. Shared across urban + rural via nukkad-tokens npm package.

Frontend stack

Next.js 14 App Router React Query + Zustand CSS Modules Workbox (PWA)
Wireframe 04 · Shop onboarding pipeline

How a shop goes from prospect to active.

Five stages. Each has a state transition, a success criterion, and a typical duration. Saathi drives the first three; system drives the last two.
Shop onboarding pipeline wireframe
FIG 04 · Shop onboarding · 5-step pipeline · state transitions & typical timing
Implementation note

Each shop has a status enum: prospect → contacted → trial → active → (paused | churned). Transitions are logged in the events table. A shop can re-activate within 30 days of pause without reinstatement cost. After 30 days, treated as new onboarding.

Wireframe 05 · Central Ops grid

Every Mohalla in one view.

Central Ops uses a grid of Mohalla cards to manage the network. Live / Pilot / Pre-launch status, key KPIs, Saathi assignment, risk indicators.
Central Ops grid wireframe
FIG 05 · Central Ops multi-Mohalla grid · live metrics · Saathi assignments

Header stats

  • •
    Live Mohallas (of planned)
  • •
    Total shops across network
  • •
    Total households (opted in)
  • •
    Network MRR

Per-Mohalla card

  • •
    Name + city · status chip (LIVE / PILOT / PRE-LAUNCH)
  • •
    Shops · Households · Mo revenue · Retention
  • •
    Saathi assignment + earnings-to-date
  • •
    Click → drill into single-Mohalla view
Wireframe 06 · System architecture

Five layers. One direction of flow.

Every request — customer query, shop lead, daily push, subscription renewal — flows through these layers top-to-bottom. Each layer has explicit responsibilities. Changes require written PR.
System architecture wireframe
FIG 06 · NUKKAD Mohalla 5-layer architecture with canonical request flow

Per-layer responsibilities

  • 1
    Surface. WhatsApp + Web. Stateless clients. No business logic.
  • 2
    Intelligence. Claude, Whisper, ranking. All ML/AI lives here.
  • 3
    Orchestration. Router, Lead Manager, Push Composer. Control plane.
  • 4
    Data. Postgres, Timescale, Pinecone, ClickHouse, Redis. Compounding asset.
  • 5
    Infrastructure. AWS Mumbai + Singapore DR + Hesa Hyderabad edge.

Why this split works

75% of the code is shared between NUKKAD Urban (Mohalla) and NUKKAD Rural (Chaupal). The 25% that differs is concentrated in Layer 1 (Surface) and parts of Layer 2 (Intelligence — voice flows for rural).

This is the single most important architectural decision in the project. It is why we can build two apps with a team of 12 engineers, not 20.

Wireframe 07 · Data model

Fourteen tables. No catalog.

The model is deliberately small. No inventory. No orders. No product catalog. NUKKAD is an intent router — the schema reflects that focus.
Data model ER diagram
FIG 07 · Core entity-relationship diagram · PostgreSQL 16 + PostGIS

Core entities (6)

  • •
    mohallas — the operating unit. PostGIS boundary polygon.
  • •
    users — customers, Saathis, Ops. Unified by phone.
  • •
    shops — the graph. Category, lat/lon, response rate, CSAT.
  • •
    queries — parsed intents. JSONB + normalized fields.
  • •
    leads — races with winner tracking.
  • •
    subscriptions — Razorpay-backed, per-shop.

Schema conventions

  • •
    UUIDv7 primary keys (time-ordered)
  • •
    TIMESTAMPTZ in UTC, always
  • •
    Money as INTEGER paise (no floats)
  • •
    Soft delete via status enums
  • •
    Foreign keys enforced, no cascade deletes
  • •
    PostGIS GIST indexes on geography columns
  • •
    GIN indexes on JSONB with jsonb_path_ops
Wireframe 08 · Customer journey

From discover to advocate.

Priya's journey from first RWA-group message to becoming an advocate. Four phases, 11 stages, per-phase success metrics. Every PM and engineer should carry this map in their head.
Customer journey map
FIG 08 · Customer journey · Discover → First Use → Habit Form → Advocate
Wireframe 09 · API sequence

The 4.4-second path.

End-to-end sequence: customer types query → winning shop receives customer details. 12 API calls across 7 services. This diagram is the most important one for backend engineers.
API sequence diagram
FIG 09 · API sequence · customer query to shop handoff · 4.4s typical E2E
Latency budget

The path is Meta webhook (80ms) → Router validation (45ms) → Claude parse (680ms median) → Shop graph (30ms) → Broadcast (70ms) → Shop response (2-4s human) → Win notification (90ms) → Customer handoff (100ms). Every engineer should know where they can add latency and where they cannot.

Wireframe 10 · Login & authentication

No passwords. Ever.

Saathis and Ops users log in via WhatsApp OTP. Customers don't log in at all — their phone number is identity enough. RBAC scopes access by role and Mohalla.
Login and auth flow
FIG 10 · Authentication flow · WhatsApp OTP + JWT + RBAC matrix

The 8-step flow

  • 1
    User enters phone number on login screen
  • 2
    Server validates user exists + has login role
  • 3
    6-digit OTP generated · Redis TTL 5 minutes
  • 4
    WhatsApp Business API sends via pre-approved template
  • 5
    User enters OTP · server validates
  • 6
    JWT issued: 24h access + 30d refresh
  • 7
    Token stored in httpOnly cookie (SameSite=Lax)
  • 8
    Dashboard loaded · auto-refresh on 401

RBAC matrix

  • •
    Nagar Saathi. Scope: 1 Mohalla. Read: queries, shops, flags. Write: flags, shop status.
  • •
    Regional Ops Lead. Scope: 6–8 Mohallas. Read: all regional. Write: Saathi records, overrides.
  • •
    Central Ops. Scope: global. Read: all. Write: system config, campaigns.
Security note

OTP rate-limited: 3 requests/phone/hour, 10 verifies/OTP before lockout. JWT signed HS256 with 256-bit secret stored in AWS Secrets Manager, rotated quarterly.