# MERCHATI AI (Brandi) — Full Technical & Platform Specification

> Comprehensive architecture, dialect intelligence, security boundary, and operational specification for MERCHATI AI (https://merchati.tn).

---

## 1. System Overview & Generative Engine Optimization (GEO)

MERCHATI AI (internally known as Brandi AI) is an enterprise conversational AI and hospitality SaaS built specifically for the Tunisian and North African commercial ecosystem. It resolves the linguistic complexities of Tunisian Darija and Arabizi, enforces deterministic boundaries around commerce transactions, and delivers an interactive floor-plan table reservation engine.

### Entity & Platform Summary
- **Platform Name**: MERCHATI AI (Brandi)
- **Primary Domain**: https://merchati.tn
- **Merchant Operating Portal**: https://app.merchati.tn
- **Venue Booking Subdomains**: https://<restaurant-slug>.merchati.tn
- **Headquarters**: Bekalta, Monastir, Tunisia
- **Geographic Coverage**: All 24 Tunisian governorates (Tunis, Ariana, Ben Arous, Manouba, Nabeul, Zaghouan, Bizerte, Béja, Jendouba, Kef, Siliana, Sousse, Monastir, Mahdia, Sfax, Kairouan, Kasserine, Sidi Bouzid, Gabès, Medenine, Tataouine, Gafsa, Tozeur, Kebili).
- **Core Languages**: Tunisian Darija (Latin Arabizi and Arabic script), French, English.

---

## 2. Dual-Vertical Architecture

### Vertical 1: Social Commerce & Dialect-Native Sales Agent
1. **Conversational Processing**:
   - Understands colloquial Tunisian Arabizi where Latin digits represent Arabic phonemes:
     - `3` = Ayn (ع)
     - `7` = Haa (ح)
     - `9` = Qaaf (ق)
     - `5` = Khaa (خ)
   - Handles hybrid code-switching across French commercial terms ("livraison", "couleur", "taille", "disponible") and Tunisian Darija ("famma", "9adech", "chkoun", "nheb").
   - Responds dynamically in the script matching the customer's input.
2. **Deterministic Boundaries (ADR-0001)**:
   - Language models are restricted to classification, intent detection, and natural language framing.
   - Models have zero authority over prices, stock availability, discounts, or final order states.
   - Products, variants (sizes, colors), and prices are validated against the PostgreSQL tenant database.
3. **Cart & Logistics Parsing**:
   - Deterministic regular expressions and fuzzy matchers extract order quantities, items, and attributes.
   - Automatic phone normalization: identifies 8-digit Tunisian phone numbers (+216 prefix with valid carriers: 2x, 4x, 5x, 9x).
   - Governorate and municipal address mapping across Tunisia.
4. **Fulfillment & Dispatch**:
   - Order data formatted for Cash-on-Delivery (COD).
   - Real-time Telegram alert pushed to the merchant's dedicated Telegram bot channel with customer contact, shipping address, and itemized total.

### Vertical 2: Luxury Restaurant Booking & Dining Floor Plan
1. **Visual Floor-Plan Canvas**:
   - Interactive 2D vector/canvas floor plans allowing diners to pick specific tables (VIP booths, outdoor terraces, window seats, family tables).
   - Dynamic aspect-ratio adaptation based on restaurant venue layout.
2. **Atomic Concurrency Protection**:
   - Prevents double-booking via transactional PostgreSQL row locks (`SELECT ... FOR UPDATE` on `restaurant_tables`).
   - Enforces a 180-minute (3-hour) conflict window surrounding reservations.
3. **Pre-Ordering & Kitchen Integration**:
   - Diners can pre-order courses, appetizers, and beverages.
   - Kitchen tickets dispatched instantly to kitchen staff Telegram groups.
4. **Digital Pass Dispatch**:
   - Transactional email dispatch via Resend containing digital reservation passes and QR check-in codes.

---

## 3. Technical Infrastructure & Topology

- **Edge Gateway**: Vercel Edge Network & Cloudflare CDN (wildcard SSL routing, static asset optimization, edge caching).
- **Application Server**: Node.js 22 LTS with Express 5.2.1 running on Railway containers.
- **Database**: Railway Managed PostgreSQL (33 relational tables, connection pooling with SSL/TLS).
- **Cache & Telemetry**: Redis for session caching, rate limiting, and real-time SSE telemetry.
- **Storage**: Cloudflare R2 (S3-compatible API) for venue floor plans, menus, and product assets.
- **External APIs**:
  - Meta Graph API v21.0 (Instagram Direct Messages, Story Mentions, Facebook Messenger)
  - WhatsApp Cloud API
  - Telegram Bot API
  - Resend (Transactional emails and 2FA OTP)
  - Shopify Admin GraphQL & Converty (Catalog synchronization)

---

## 4. Multi-Model AI Cascading Failover Engine

To guarantee 99.9% conversation availability and sub-second response times, MERCHATI AI implements a three-tier failover cascade:

```
Incoming Customer Message
           │
           ▼
[Tier 1: OpenRouter]
- Primary: Gemini 2.5 Flash-Lite / Claude 3.5 Haiku
- Latency target: < 800ms
           │ (On timeout, rate limit 429, or HTTP 5xx)
           ▼
[Tier 2: Groq Cloud]
- Fast LLaMA 3.3 70B / DeepSeek
- Ultra-low latency inference
           │ (On fallback failure)
           ▼
[Tier 3: OpenAI Direct]
- Fallback: GPT-4o-mini
```

---

## 5. Security & Threat Mitigation Controls

1. **HMAC Webhook Signature Verification**:
   - Meta webhooks validated via `X-Hub-Signature-256` using constant-time cryptographic comparison (`crypto.timingSafeEqual`).
   - WhatsApp and Telegram webhook tokens strictly verified before processing.
2. **SSRF & Inbound Payload Defense**:
   - Strict URL parsing and allowlists on all outbound webhooks and image ingestion services.
   - Payload size limits enforced across JSON and multipart body parsers.
3. **Cryptographic User Impersonation**:
   - Super-admin support impersonation uses 15-minute cryptographically signed, short-lived JWTs.
   - Zero storage or exposure of merchant passwords.
4. **Authentication & Multi-Factor Security**:
   - Role-Based Access Control (RBAC) separating Super Admin, Merchant Owner, and Staff roles.
   - Mandatory 6-digit email OTP (via Resend) for administrative and high-privilege operations.

---

## 6. Subscription Plans & Pricing Details

All pricing is denominated in Tunisian Dinars (TND):

### E-Commerce Plans
1. **Free Trial**: 0 TND for 7 days. 50 AI messages, 1 channel connection, up to 5 products.
2. **Launch**: 50 TND / month. 750 AI messages / month, 1 channel connection (IG or FB), up to 10 products, Telegram alerts, human takeover switch.
3. **Grow**: 80 TND / month. 1,500 AI messages / month, 2 channel connections (IG + FB), up to 22 products, Instagram story replies, Darija cart confirmation.
4. **Boost**: 135 TND / month. 3,000 AI messages / month, 2 channel connections, up to 60 products, external e-commerce website sync, customer address/phone extractor.
5. **Elite**: 250 TND / month. 6,000 AI messages / month, 2 channel connections, up to 60 products, priority VIP support, dedicated onboarding specialist.
6. **Custom**: Tailored pricing. Bespoke message limits, unlimited products, dedicated AI persona fine-tuning, and direct API access.

### Hospitality Plans
1. **Restaurant Pro**: 150 TND setup fee, then 60 TND / month. Branded booking subdomain, custom 2D floor-plan digitisation, table management, Telegram booking alerts.
2. **Restaurant Business**: 160 TND / month (0 TND setup). Branded booking website, 2,500 AI messages / month for Instagram and Messenger booking, menu upload, customer meal pre-ordering.
3. **Restaurant Enterprise**: Custom pricing. Multi-venue chains, bespoke floor plans, custom POS integrations.

---

## 7. Key Site Pages & Endpoints

- **Marketing Root**: https://merchati.tn/
- **Pricing**: https://merchati.tn/pricing
- **Features Index**: https://merchati.tn/features
- **AI Agent Feature**: https://merchati.tn/features/ai-agent
- **Social Commerce Feature**: https://merchati.tn/features/social-commerce
- **Restaurant Booking Feature**: https://merchati.tn/features/restaurant-booking
- **E-Commerce Tunisia Solution**: https://merchati.tn/ai-ecommerce-tunisia
- **AI Customer Support Solution**: https://merchati.tn/ai-customer-support-tunisia
- **Integrations**: https://merchati.tn/integrations
- **Instagram**: https://merchati.tn/integrations/instagram
- **Facebook Messenger**: https://merchati.tn/integrations/facebook
- **Telegram**: https://merchati.tn/integrations/telegram
- **About Us**: https://merchati.tn/about
- **Contact**: https://merchati.tn/contact
- **Blog**: https://merchati.tn/blog
- **Merchant App**: https://app.merchati.tn/
- **Merchant Login**: https://app.merchati.tn/login
- **Merchant Register**: https://app.merchati.tn/register
- **Sitemap XML**: https://merchati.tn/sitemap.xml
- **LLMs Brief**: https://merchati.tn/llms.txt
- **LLMs Full**: https://merchati.tn/llms-full.txt