HHMatrics · Multi-Branch Retail Platform

Your data model & system flow, in plain view

This is the blueprint of every piece of information the system stores and how it moves — from a customer browsing online to a follow-up message after they visit a store. Review it, and tell us anything you want added, renamed, or changed.

PK Unique record ID FK Links to another table UK Must be unique Relationship
01

The data model

Each box is a table of records. Grouped by what it does. Every table tied to a branch is kept strictly separate per store — one branch can never see another branch's data. Only the Super Admin sees everything.

Branches & Staff Access

Branch

A physical store location.

  • idPK
  • name / slugUK
  • regiontext
  • lat / lngmap pin
  • whatsappphone

has many staff, customers, products, invoices

Account

Login for any staff member.

  • idPK
  • phoneUK
  • passwordHashsecured
  • role4 roles
  • systemKeyIT only

is one Manager or Salesman

Manager

Runs one branch.

  • idPK
  • accountIdFK
  • branchIdFK
  • fullNametext

belongs to one Branch

Salesman

Serves customers on the floor.

  • idPK
  • accountIdFK
  • branchIdFK
  • fullNametext

handles many Interactions

Login Security

Sessions & Super Admin one-time codes.

  • RefreshTokensessions
  • OtpChallengeOTP codes

keeps logins safe & revocable

Customers & Sales

Customer

A shopper. Duplicates are auto-merged by name + mobile.

  • idPK
  • branchIdFK
  • fullName / phoneUK
  • age / sizeprofile
  • birthdaygreetings
  • optedOutstop msgs

has interactions, invoices, reviews, messages

Interaction

One visit — salesman meets customer.

  • idPK
  • customerIdFK
  • salesmanIdFK
  • productRefviewed item
  • statusbought / not

yields one Review

Review

Feedback via a private link.

  • idPK
  • interactionIdFK
  • productStars1–5
  • salesmanStars1–5
  • droppingCausewhy not bought

rates a Product & a Salesman

Catalog & 3D

Product

An item in a branch's inventory.

  • idPK
  • branchIdFK
  • title / slugUK
  • pathready-made / fabric
  • sizes / colorsoptions
  • price / badgesoffers

has photos & a 3D model

Product Asset

Each photo, plus its generated 3D avatar.

  • idPK
  • productIdFK
  • imageUrlraw photo
  • gltfUrl3D file
  • statusprocessing state

belongs to one Product

Billing, Messaging & Server Health

Invoice

Pulled from your billing software's export files.

  • idPK
  • branchIdFK
  • customerIdFK
  • externalIdUK
  • amount / linesbill detail

re-imports never double-count

Outbox Message

Every WhatsApp/SMS Hermes sends.

  • idPK
  • customerIdFK
  • channelwhatsapp / sms
  • kindthank-you, offer…
  • statussent / delivered

transport can be swapped anytime

Telemetry Sample

Snapshots of server health.

  • idPK
  • cpuTempCtemperature
  • ramUsedPctmemory
  • containersrunning apps

alerts IT if temp > 75°C

02

The customer journey

How a single shopper flows through the system — and where automated messages fire.

Customer browses the websitecatalog · branch search · 3D preview
Visits the branch in person
Salesman fills the intake formmobile · name · age · size · product
Already a customer?matched by name + mobile number
yes
Add to existing profilehistory stays in one place
no
Create new profile
Did they buy?
bought
Hermes sends thank-you + cross-sellinvoice pulled in automatically
not bought
Hermes sends product link + short surveyprice? size? look? fabric?
Feedback captured in the review portal
03

How the system is built

All of this runs on one in-house Ubuntu server — no monthly cloud fees. Messages go out through WhatsApp directly, without paying for the official business API.

What people use

Public websitecustomers browse & find branches
Staff dashboardssalesman · manager · admin · IT

↓ secured by Nginx (encrypted HTTPS)

The brains

Web appNext.js — fast, search-friendly pages
Core APINestJS — logins, rules, branch isolation

↓ stores & queues work

Data & background work

PostgreSQLthe database — all records above
Redistask queue & fast cache
Hermes enginemessaging, greetings, imports, alerts
AI serviceturns photos into 3D avatars

Hermes → customer WhatsApp · billing export files → import · server heat → IT alert

04

Want a change?

Tell us in plain language — we'll adjust the blueprint

  1. Point at any box or arrow above — e.g. "Customer should also store an email," or "add a Loyalty Points table."
  2. We update this diagram and the underlying database design to match.
  3. If a change goes beyond the agreed scope, we'll flag the impact on time/cost before building it.