TiliGems — Complete Platform Blueprint
Premium natural-gemstone commerce + intelligence platform. Built on Base44 (React + Tailwind + Vite), Stripe payments, GTM/GA4/Meta analytics, and a database-backed SEO + multi-template engine.
Tip: click Download as PDF and choose “Save as PDF” as the destination.
1. Tech Stack & Architecture
Frontend: React 18 + Tailwind CSS + Vite, shadcn/ui, lucide-react, recharts, react-leaflet, framer-motion, react-quill, @hello-pangea/dnd, three.js, react-markdown.
Backend: Base44 serverless functions (base44/functions/*/entry.ts), Base44 database (JSON-schema entities), Base44 workflows, Base44 auth.
Payments: Stripe Checkout (test mode → live via own keys). Secrets: STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY.
Design system: CSS-variable token theme (src/index.css) mapped in tailwind.config.js. ThemeContext swaps CSS variables + a data-theme-style attribute site-wide. 11 templates, 6 structural styles.
Routing: src/App.jsx — AuthProvider → QueryClientProvider → CurrencyProvider → ThemeProvider → Router. Public pages under AppLayout; admin under AdminRoute → AdminLayout; account under ProtectedRoute.
2. Public Frontend — Pages & Routes
Global chrome (AppLayout): persistent left sidebar (logo video, contact, WhatsApp crystal button, nav, auth), top bar (search, cart, currency switcher, account), footer (newsletter, links, socials, KiwiNova credit), floating WhatsApp, floating AI Advisor diamond.
| Route | Page | What it does |
|---|---|---|
| / | Home | Hero slideshow, shop-by-category, shop-by-shape, price nav, featured gems, optional About/Contact/Trust (toggleable via HomepageConfig). |
| /shop | Shop | Full catalogue, right-hand filter sidebar, search, sort, URL-synced filters, wishlist, mobile drawer. |
| /product/:slug | Product Detail | Gallery + 360°, full gemological specs, certification, origin story, share (product OG), enquiry, Find Similar, calculator. |
| /collections | Collections | Curated collection gallery with counts + sample images. |
| /investment-stones | Investment Stones | Ranked investment-grade stones. |
| /jewelry | Jewellery | Jewellery items (is_jewelry = true). |
| /gemstone-finder | Gemstone Finder | Step-by-step quiz → matching products. |
| /birthstones | Birthstones | Month/zodiac → birthstone + in-stock gems. |
| /education, /education/:slug | Education Hub | Article listing + detail with comments + share. |
| /international, /international/:slug | Country Pages | SEO country landing pages. |
| /about | About | Heritage, values, timeline, world map, country grid. |
| /contact | Contact | Contact form → Enquiry. |
| /cart | Cart | Line items, totals → checkout. |
| /checkout/success | Checkout Success | Verifies Stripe, marks order paid, stores address. |
| /wishlist | Wishlist | Saved gemstones (localStorage). |
| /account | Account | Protected — profile, orders, wishlist. |
| /login, /register, /forgot-password, /reset-password | Auth | Email+password, Google OAuth, OTP, reset. |
| /privacy, /terms, /returns | Legal | Policy pages. |
| /sitemap.xml, /robots.txt | SEO endpoints | Backend-function redirects. |
3. Admin Dashboard — Every Tab (/admin/*)
Admin is gated by AdminRoute (admin role only). Sidebar groups:
- •Dashboard: Overview, Enquiries, Leads, Customers
- •Gemstone Management: All Gemstones, Add Gemstone, Categories, Investment Stones
- •Jewellery Management: All Jewellery, Add Jewellery
- •Education: Articles, Add Article
- •Accounts: Analytics, Inventory, Invoicing (Invoices + Payment Transactions tabs)
- •Migration: GemIQ Migration, Image Migration
- •SEO & Digital Growth: SEO Control Centre (Dashboard, Settings, Keywords, Redirects, Internal Links, Countries, Audit, Site Health, Change Log, Assistant)
- •System: Website (Homepage, Hero, Categories, Templates), Settings, User Guide, Recycle Bin
4. Data Model (Entities)
- •Commerce: Product (80+ fields), Order (Stripe-linked), Invoice, Customer, Category, Collection
- •Content: Article, Comment, HeroSlide, HomepageConfig
- •Leads: Enquiry, Lead, NewsletterSubscriber, WishlistItem
- •SEO: SeoSettings, SeoKeyword, SeoRedirect, SeoAuditIssue, SeoChangeLog, CountryPage
- •Theming: Theme (name, key, swatches, is_active, is_default, display_order); style derived from THEME_STYLES map
- •System: SiteSettings, ImportBatch, ImageMigrationLog, RecycleBin, User (built-in admin/user roles)
5. Backend Functions (base44/functions/)
Workflow: DailyGemEducation.jsonc — scheduled daily AI article generation.
| Function | Purpose |
|---|---|
| createCheckout | Validates cart, creates Stripe session (shipping+billing, app-id metadata), creates Order (pending) + upserts Customer. |
| verifyCheckout | Fetches Stripe session, marks Order paid, stores payment_intent + shipping_address. |
| submitProductEnquiry | Product enquiry → Enquiry + optional email. |
| replyToCustomer | Admin reply via email. |
| gemiqImport | Pull + map GemIQ feed into Products. |
| generate360 | Generate 360° video asset. |
| analyzeProductColours | AI colour analysis. |
| generateEducationArticle | AI article (daily workflow). |
| generateSeoContent | AI SEO copy. |
| generateCountryPage | AI country-page content. |
| generateSitemap / getRobotsTxt | Dynamic sitemap.xml + robots.txt. |
| runSeoAudit / checkSiteHealth | SEO + broken-link/speed audit → SeoAuditIssue. |
| recommendInternalLinks | Suggests internal links. |
| detectCurrency | Geo-detect visitor currency. |
| proxyImage / sharePreview | Image proxy + social-share preview. |
| exportBackup / importBackup | JSON backup/restore. |
| gemAdvisorChat | LLM AI Gem Advisor. |
6. Payment Flow (Stripe) — End to End
- •1. Customer adds gemstones to cart (/cart), selects Checkout.
- •2. Frontend calls createCheckout with cart items.
- •3. createCheckout requires signed-in user, re-validates each item (published, not enquiry_only, has price), builds Stripe line items, creates Checkout session with shipping+billing collection + app-id metadata, creates Order (pending), upserts Customer, returns Stripe URL.
- •4. Customer pays on Stripe, enters shipping/billing address.
- •5. Stripe redirects to /checkout/success?session_id=...
- •6. verifyCheckout fetches session, marks Order paid, sets payment_date + stripe_payment_intent, builds delivery address → shipping_address.
- •7. Admin tracks paid order in Invoicing → Payment Transactions, updates fulfilment + shipping notes.
- •Going live: Dashboard → Integrations → Stripe → provide own API keys. Test card: 4242 4242 4242 4242.
7. Customer Journey
- •Discover: Home → Shop (filter/search) → Product detail (360°, certification, calculator) → Gemstone Finder / Birthstones.
- •Engage: WhatsApp crystal button (sidebar) or floating WhatsApp → chat. AI Advisor diamond → LLM recommendations with product links. Share to FB/WhatsApp/LinkedIn (product-specific OG).
- •Convert: Add to cart → Stripe checkout → success. Currency auto-detected + switchable (28 currencies).
- •Enquiry-only stones: hides price, replaces Add-to-Cart with enquiry form → Enquiry → admin pipeline.
- •Post-purchase: Account shows orders; admin updates shipping; replies via replyToCustomer.
- •Retention: Wishlist, Newsletter, Education articles + comments.
8. Theme / Template System
How it works: ThemeContext loads active Theme, applies CSS vars to :root, sets data-theme-style on <html>. index.css has per-style rules for sidebar artwork, card shape/border/shadow, gem shine overlay, nav indicator, logo lettering. WhatsApp crystal + AI diamond use hsl(var(--gem)) so they recolour per template. Switch in Website → Templates.
| Template | Style | Look |
|---|---|---|
| Maroon & Gold (default) | classic | Deep-maroon + coral gems + gold |
| Pink & White | classic | Bright pink, hot-pink gems, white cards |
| Champagne | classic | Warm golden-yellow |
| Royal Gold | classic | Espresso-gold + bronze |
| Noir Black & White | noir | White bg, black surfaces, silver, pinstripe sidebar |
| Mint Green | classic | Light green + emerald |
| Sky Blue | classic | Airy blue + sapphire |
| Emerald Deco | deco | Art-Deco sunburst sidebar, geometric gold-trimmed cards |
| Royal Velvet | baroque | Royal purple, damask sidebar, ornate gold frames |
| Azure Aurora | aurora | Teal, soft glow, rounded glowing cards |
| Amethyst Prism | prism | Amethyst, faceted sidebar, angular cards, crystalline shine |
9. SEO Infrastructure
- •Technical: dynamic sitemap.xml + robots.txt, per-route <Seo> (title, description, canonical, OG, Twitter, JSON-LD), SeoRedirect (301/302/410), prelaunch_noindex.
- •Tracking: GTM + GA4 + Meta Pixel via AnalyticsInjector with dataLayer events (view, add-to-cart, purchase).
- •Verification: Search Console, Bing, Facebook domain tokens in SeoSettings.
- •Structured data: Organization, Website (SearchAction), Product (offers/availability), BreadcrumbList.
- •Localisation: CountryPage per market (currency, shipping, buying info, FAQ, keywords, indexable).
- •Optimisation: runSeoAudit + checkSiteHealth → SeoAuditIssue; recommendInternalLinks; SeoKeyword tracking; SeoChangeLog; AI SeoAssistant.
- •Social: sharePreview + product-specific OG tags (image/description per product).
10. Site Settings
- •SiteSettings (Website → Settings): logo video URL, company, WhatsApp, socials, GA4, currencies, exchange rates, default SEO/OG.
- •SeoSettings (SEO → Settings): canonical domain, GTM/GA4/Meta IDs, verification tokens, robots, noindex, sitemap/schema toggles, launch-ready.
- •HomepageConfig (Website → Homepage): toggle + edit hero/categories/shapes/prices/featured/trust/about/contact.
- •Theme (Website → Templates): activate any of 11 templates — restyles entire site instantly.
11. How the System Works — End to End
- •1. Visitor lands → AppLayout renders sidebar + top bar. CurrencyContext detects currency; ThemeContext applies template; AnalyticsInjector fires pageview.
- •2. Browse → Shop/collections/finder pull published Products via base44.entities.Product. Filters/sort client-side; URL params persist.
- •3. Product detail → loads by slug, increments views, shows 360°/specs/cert, product OG share, enquiry → submitProductEnquiry.
- •4. Cart → Checkout → createCheckout (server validates) → Stripe session → Order + Customer → redirect to Stripe.
- •5. Payment success → verifyCheckout marks Order paid + stores address. Admin sees it in Payment Transactions.
- •6. Admin manages everything via tabbed console: products, inventory, invoicing, enquiries/leads/customers, SEO, migration, themes, settings.
- •7. Automation → daily workflow generates articles; SEO audit on demand; image/GemIQ migrations batch-import.
- •8. Theming → switching template updates DB is_active flags, ThemeContext reloads, CSS vars + data-theme-style change → entire site restyles instantly.