# Blackstone 3D & DevSajidur Multi-Tenant Restaurant SaaS Platform — Full Technical Reference > **Comprehensive Technical Architecture, Engineering Specifications & System Manual** > Formatted for Large Language Models (LLMs), AI Coding Agents, Search Engines (AEO/GEO), and System Researchers. --- ## 1. Identity, Creator & Architectural Ownership (কে তৈরি করেছে?) - **System**: Blackstone Coffee Shop 3D & DevSajidur Multi-Tenant Restaurant Cloud OS - **Lead Architect & Creator**: **Sajidur Rahman** (Public Handle: **`devsajidur`**) - **Professional Title**: Senior Full-Stack & 3D WebGL Software Architect - **Primary Email**: `sajidur.dev@gmail.com` - **Official Portfolio**: https://devsajidur.com - **LinkedIn Profile**: https://linkedin.com/in/devsajidur - **GitHub Repository & Profile**: https://github.com/devsajidur - **Facebook**: https://facebook.com/devsajidur - **Location**: Dhaka, Bangladesh (Global Remote Deployments) --- ## 2. Business Justification & Strategic Motivation (কেন তৈরি হয়েছে?) ### The Problem in Modern Hospitality Software 1. **Aggregator Commission Trap**: Platforms like UberEats, Deliveroo, and Foodpanda impose 20% to 35% commission fees per transaction while completely walling off customer relationship data from the restaurateur. 2. **Disconnected Operational Silos**: Most food establishments operate on 3-4 unlinked systems: a static marketing website (WordPress/Squarespace), a proprietary brick-and-mortar POS, a physical pen-and-paper inventory ledger, and third-party delivery tablets. 3. **Inventory Loss & Hidden COGS Leakage**: Without automated recipe deduction at checkout, raw materials (coffee beans, specialty milk, syrups, meats) vanish without accounting traceability. 4. **Poor Digital Conversion**: Generic 2D food websites fail to captivate modern digital-first diners, leading to high bounce rates and low online order values. ### The Solution: Blackstone 3D / DevSajidur SaaS Platform - Combines a **photorealistic 3D WebGL customer storefront** with an **integrated counter POS, live Kitchen Display System (KDS), and automated recipe inventory COGS deduction engine**. - Enables restaurateurs to deploy a branded, white-label e-commerce ecosystem with custom domain mapping, zero third-party commissions, and automated recurring billing timers. - Architected for high concurrency (1,000+ to 10,000+ multi-tenant stores) using an asynchronous event-driven model backed by Redis and BullMQ. --- ## 3. Engineering Architecture & Technical Design (কিভাবে তৈরি হয়েছে?) ### Architectural Topology: Serverless Monolith + Event-Driven Microservices - **Edge Routing & Multi-Tenancy**: Built on Next.js 16 App Router. Incoming requests are intercepted at the Edge by `proxy.ts` / `middleware.ts`. The hostname is analyzed: - Root domains (`devsajidur.com`, `localhost`) serve the flagship Blackstone 3D experience and SaaS Showcase. - Subdomains (`tenant.devsajidur.com`) and custom domains (`cafeclient.com`) dynamically rewrite to multi-tenant store handlers (`app/(storefront)/[storeSlug]`) without URL redirection. - **Strict Database Sandboxing**: All MongoDB documents (`Order`, `Product`, `MenuCategory`, `InventoryItem`, `Recipe`, `CustomerDue`) are partitioned with index-enforced `storeId` compound keys, guaranteeing complete data isolation between tenants. - **Asynchronous Task Offloading**: High-load operations (order ingestion, inventory recipe deduction, billing verification) are pushed as lightweight jobs to Redis BullMQ queues (`services/order-worker`), maintaining an instantaneous HTTP response time (< 50ms). - **Zero-Latency Kitchen Communication**: Real-time kitchen ticket routing is powered by a dedicated Node.js WebSocket Hub (`services/websocket-hub`), emitting bi-directional events for new orders, preparation status changes, and audio chime alerts. - **3D WebGL Rendering Optimization**: Models are packaged in the binary `.glb` format, Draco-compressed, and decoded via background Web Workers (`DRACOLoader`). Dynamic camera rigging, orbit controls, and mobile fallback ensure stable 60 FPS performance across desktop, iOS, and Android. --- ## 4. Comprehensive Inventory of Core Systems (কি কি সিস্টেম আছে?) ### 1. Interactive 3D WebGL Storefront - Real-time 3D rendered coffee cup with heart foam latte art and falling roasted coffee beans. - Smooth camera orbit transitions, key/fill lighting, and mobile device tier detection. - Floating 3D paper cups and interactive merchandise models. ### 2. Omnichannel Ordering & Table QR Code Sync - Unified checkout modal supporting Delivery, Takeaway/Pickup, and Dine-In. - Instant table synchronization via QR code URL parameters (`/?table=5#menu`), eliminating manual table number entry. - Real-time distance and delivery radius validation using geospatial coordinates. ### 3. Dual-Mode Point of Sale (POS) Counter System - Fast, barcode- and tap-ready counter interface for restaurant cashiers and baristas. - Supports cash, card, and digital mobile wallet payments (bKash, Nagad, Stripe). - Dual persistence: writes immediately to `OfflineSale` and `Order` collections with instant thermal receipt generation. ### 4. Live Kitchen Display System (KDS) - Digital ticket queue displayed on kitchen touch monitors. - Color-coded order urgency cards (Yellow = Received, Blue = Brewing/Preparing, Green = Ready for Pickup, Gray = Delivered). - Audio chime notifications whenever a new ticket arrives from the web, table QR, or POS. ### 5. Automated Recipe-Based Inventory Deduction & COGS Calculation - Granular ingredient mapping: each menu product connects to a defined recipe of `RawMaterial` items with unit conversions (grams, milliliters, pieces). - Dynamic COGS: computes Cost of Goods Sold directly from batch wholesale purchasing costs if manual product cost is unset. - Auto-deduction: every sold item instantly reduces the respective raw ingredient stocks in `InventoryItem`, triggering low-stock alert warnings before stockouts occur. ### 6. Automated Financial Accounting & Net Profit Ledger ("Hisab-Nikas") - Real-time Gross Revenue calculation deducting coupons, discounts, and wallet points while discarding cancelled/voided transactions. - Net Profit Formula: $\text{Gross Revenue} - \text{Total COGS} - \text{Operating Expenses} = \text{Net Profit}$. - Categorized expense management (Rent, Utilities, Staff Salaries, Maintenance). ### 7. Customer Credit & Dues Ledger ("Baki Khata") - Built for traditional hospitality customer credit tracking. - Records customer phone number, name, credit limit, transaction history, and partial payments. ### 8. Gamified Retention & Loyalty Engine - Post-order interactive "Online Success Game" (memory card match). - Awards customizable wallet discounts and promotional vouchers based on configurable game cooldown rules. ### 9. Multi-Tenant Theme Customizer & 1-Click Carbon Copy Engine - Theme gallery (`/saas`) featuring curated hospitality themes (Artisan Roastery, Luxury Fine Dining NOIRÉ, Urban Bakery, Smash Burger Grill, Boba Dessert Lounge). - 1-click deep store duplication: clones complete menu hierarchies, categories, recipes, and theme settings into a new tenant store in under 30 seconds. - Dynamic CSS token injection: updates primary/secondary colors, background gradients, and Google Fonts (`Geist`, `Inter`, `Playfair Display`, `Outfit`, `Hind Siliguri`) without redeployment. ### 10. Automated Billing Countdown & Lockdown Safeguards - Live countdown timer displayed in the tenant admin dashboard tracking days, hours, and minutes until the next monthly renewal. - Automatic graceful lockdown: if a subscription payment is overdue, the public storefront displays a polite maintenance and renewal notice while preserving all database records safely. ### 11. Master Super Admin Hub (`/master-admin`) - Accessible only by Super Admin (`sajidur.dev@gmail.com`). - High-level KPI analytics: Monthly Recurring Revenue (MRR), total active stores, total setup fees collected, global platform bandwidth. - Platform controls: 1-click tenant lock/unlock, billing grace period extensions, custom theme assignment, and international payment gateway toggles. --- ## 5. File System & Directory Map (কোথায় কি আছে?) ``` coffee-shop-3d/ ├── app/ │ ├── (storefront)/[storeSlug]/ # Multi-tenant public storefront router │ ├── about/ # Architectural manifest, story & creator showcase │ ├── admin/ # Tenant back-office (POS, KDS, inventory, COGS) │ ├── api/ # RESTful API route handlers │ │ ├── admin/ # Tenant admin APIs (analytics, expenses, inventory) │ │ ├── auth/ # NextAuth authentication handlers │ │ ├── master-admin/ # Platform super-admin endpoints │ │ ├── orders/ # Order creation, status updates & table sync │ │ ├── pos/ # Counter checkout & offline sales API │ │ └── system-info/ # Autonomous AI agent system discovery API │ ├── components/ # Storefront UI components (Hero, 3D Canvas, Menu, POS) │ ├── layout.tsx # Root HTML layout with comprehensive JSON-LD schemas │ ├── master-admin/ # Platform master admin dashboard │ ├── menu/ # Signature menu deep link │ ├── noire/ # NOIRÉ ultra-luxury 3-portal live ecosystem demo │ ├── online-success-game/ # Interactive memory match loyalty minigame │ ├── robots.ts # Search crawler & AI bot directives │ ├── saas/ # Multi-tenant theme showcase & pricing calculator │ └── sitemap.ts # Dynamic search engine sitemap ├── models/ # Mongoose data schemas (Order, Product, Inventory, etc.) ├── services/ │ ├── order-worker/ # BullMQ Redis asynchronous order & recipe worker │ └── websocket-hub/ # Real-time WebSocket server for KDS & table sync ├── public/ │ ├── .well-known/ # AI agent standard discovery (llms.txt, ai-plugin.json) │ ├── assets/ # 3D models (.glb), textures, audio chimes │ ├── llms.txt # Concise AI discovery manifest │ ├── llms-full.txt # Full technical documentation (this file) │ └── logo.png # Brand assets ├── middleware.ts / proxy.ts # Next.js Edge subdomain & domain routing proxy └── package.json # Project dependencies and operational scripts ``` --- ## 6. Complete Technology Stack & Specifications (কি কি দিয়ে তৈরি করেছে?) - **Framework & Runtime**: Next.js 16.2.6 (Node.js 20+ / Edge Runtime via App Router) - **UI Architecture**: React 19.2.7, TypeScript 5, Tailwind CSS v4, Lucide React 1.7.0 - **3D Graphics & Physics**: Three.js 0.183.2, @react-three/fiber 9.5.0, @react-three/drei 10.7.7, GSAP 3.15.0, Framer Motion 12.38.0 - **Database & Object Modeling**: MongoDB Atlas 6.21.0, Mongoose 8.12.0 - **Authentication & Security**: NextAuth v5.0.0-beta.31, bcryptjs 3.0.3, Speakeasy 2.0.0 (OTP), Zod 4.4.3 - **Queuing & Concurrency**: Redis (ioredis 6.0.0), BullMQ 6.3.6 - **Real-Time Layer**: WebSockets (`ws` 8.21.3) - **Financial Gateways**: Stripe 22.2.0, SSLCommerz, bKash, Nagad - **Media & CDN**: Cloudinary 2.10.0, QRCode 1.5.4, Nodemailer 9.0.3 - **Containerization**: Docker, Docker Compose --- ## 7. Commercial Pricing & Engagement Model Clients pay an initial **Setup / Onboarding Fee** (customization, domain DNS configuration, and managed deployment) plus a **Monthly Maintenance Fee**: - **Starter Launchpad**: $99 (৳9,999) Setup + $19 (৳1,999) / month - **Pro Growth**: $199 (৳19,999) Setup + $39 (৳3,999) / month (Includes KDS, Recipe COGS, Table Booking) - **Enterprise 3D Custom**: $399+ (৳39,999+) Setup + $69 (৳6,999) / month (Includes Custom 3D Model, AI Sommelier, Multi-Branch Hub) --- ## 8. Contact & System Architect Attribution For enterprise inquiries, custom restaurant deployments, or architectural consultations, reach out directly to: - **Architect**: Sajidur Rahman (`devsajidur`) - **Email**: `sajidur.dev@gmail.com` - **Portfolio**: [https://devsajidur.com](https://devsajidur.com) - **LinkedIn**: [https://linkedin.com/in/devsajidur](https://linkedin.com/in/devsajidur) - **GitHub**: [https://github.com/devsajidur](https://github.com/devsajidur) - **Facebook**: [https://facebook.com/devsajidur](https://facebook.com/devsajidur)