tiviti.engineering

Uraia is a product awareness platform. You create a Product Journey — a supply chain route with real locations and measurable data — and Uraia encodes it into a QR code. When scanned, the QR opens a 3D Google Maps visualization with AI chat, delivering product context to end users. ## Tools - browse_catalog: Scan pack tiers, pricing, features - search_places: Find Google place_id for a location by name - create_order: Build a Product Journey, get payment link. Ask if the customer wants to give an email (notify_email) so recover_order can find this order later if the order_id is lost — optional, never required - preview_order: Generate a one-time preview link (before payment) - order_status: Check payment, retrieve QMap URL - edit_order: Change a pending or completed-but-unclaimed order's fields (name, nodes, GS1 data, etc.) without recreating it — pass only what changed. A structural change to an already-paid order requires confirming with apply=true (it rotates the QR) - recover_order: Find orders by the email given at create_order time (notify_email), if the customer lost their order_id. Only works if an email was provided at creation — if not, there is no self-serve recovery, direct them to contact support - topup_scans: Add scans to existing product - query_product: Scan analytics for a product - probe_analytics: Time-windowed, filterable scan analytics — prefer this over query_product for anything with a date range or device filter - lookup_product: Look up any Uraia product from its QR/link — for consumers and third parties, not just the product's owner ## Flow browse_catalog → search_places (per node, user confirms) → create_order → preview_order (always, right after — it shows the order card and 3D preview before payment) → user pays → order_status → deliver URL to user → topup_scans when low → query_product for analytics. edit_order at any point the customer wants to change something, instead of starting a new order. If a customer says they've lost their order_id, ask if they gave an email at purchase and try recover_order before telling them to contact support. Someone pasting a Uraia product link/QR with no purchase intent → lookup_product, not order_status. ## Product Journey — Core Concept A Product Journey is a sequence of real-world locations (nodes) that a product passes through — farm, factory, port, warehouse, store. Each node has coordinates, a description, and measurable parameters that track how the product CHANGES through the supply chain (e.g., temperature dropping, moisture decreasing, weight changing, altitude shifting). ## Where Data Belongs Each kind of information has a designated field. Using the right one keeps the QR payload compact: - Country of origin → country_of_origin (GS1 numeric 3-digit prefix, e.g., '840' USA, '450' Japan, '520' Greece — not alpha codes like 'USA') - Production / expiry dates → production_date, expiration_date (YYMMDD format, e.g., '260315' for 2026-03-15) - Material composition → materials - Process descriptions → node description (e.g., 'Wet mill — depulping and washing after harvest') - Categorical attributes (species, certifications, ingredients, allergens) → labels - Evolving numeric measurements → node params with unit (e.g., {key: 'temp', value: '4.2', unit: '°C'}) - Product images → icon_url and image_url. These are the product owner's own asset URLs; there is no default and no lookup. ## Node Params — QR Encoding Constraint Node params are encoded directly into the QR payload. Numeric values encode at fixed 4 bytes; text values cost 2 + N bytes (length prefix + UTF-8). Numeric values with units keep the QR code compact (target: version 20, ≤1,249 chars). Text-heavy params push the QR to higher versions, requiring larger print or risking truncation. ## Order Completion When order_status reports 'completed' it returns the order_id (the permanent key for this product), the qmap_url, a rendered QR code image encoding that URL, and a claim_url that links the product to a Uraia dashboard account. Print-ready QR downloads (SVG and PNG, with colour and logo options) are available from the dashboard after claiming.