01 — System Overview

Product: RestaurantOS — Dynamic QR-Based Multi-Tenant Restaurant SaaS Platform Version: 1.0.0 Status: Frontend/UI implemented on mock data · Backend spec below is the target production architecture Audience: Founders, architects, engineering leads, AI coding agents (Claude/Copilot), new contributors

📖 কীভাবে পড়বেন (How to read this doc): প্রতিটি সেকশনে প্রথমে ইংরেজিতে টেকনিক্যাল স্পেসিফিকেশন থাকবে, তারপর নিচে 🟢 বাংলা সারাংশ ব্লকে সংক্ষিপ্ত ব্যাখ্যা থাকবে। কোড/স্কিমা অংশ শুধু ইংরেজিতেই থাকবে যেহেতু কোড ভাষা-নিরপেক্ষ।

1. Product Vision

RestaurantOS is a single codebase, single deployment SaaS platform that lets any number of independent restaurants ("tenants") run their entire dine-in, delivery, and pickup operation — digital menu, kitchen display, waiter coordination, delivery riders, marketing promos, POS, and business analytics — without installing hardware-locked POS software or maintaining their own website.

A diner scans a QR code on a physical table → lands on that restaurant's branded digital menu → orders, pays, and tracks status — all without an app install. A restaurant owner signs up once and gets a fully branded, isolated instance of the platform reachable at their own subdomain (swadh-ghar.restaurant-os.com) or their own custom domain (menu.kacchibhai.com), configured entirely from a self-serve dashboard — no support ticket, no code change, no redeploy.

The platform itself is operated by a Platform Admin team who onboard tenants, manage subscription billing, toggle feature availability per plan, and monitor system health across every restaurant from one super-admin console.

🟢 বাংলা সারাংশ: RestaurantOS হলো একটি SaaS প্ল্যাটফর্ম যেখানে একটি মাত্র কোডবেস দিয়ে অসংখ্য রেস্টুরেন্ট (প্রতিটি একটি "tenant") তাদের সম্পূর্ণ অপারেশন — ডিজিটাল মেনু, কিচেন ডিসপ্লে, ওয়েটার, রাইডার, প্রোমো, POS, অ্যানালিটিক্স — একটি জায়গা থেকে চালাতে পারে। কাস্টমার QR স্ক্যান করে সরাসরি অর্ডার করতে পারে, কোনো অ্যাপ ইনস্টল ছাড়াই। প্রতিটি রেস্টুরেন্ট তাদের নিজস্ব সাবডোমেইন বা কাস্টম ডোমেইনে চলে, এবং প্ল্যাটফর্ম অ্যাডমিন টিম সব রেস্টুরেন্ট একসাথে মনিটর ও ম্যানেজ করে।

2. Tech Stack

🟢 বাংলা সারাংশ: ফ্রন্টএন্ডে Next.js 16 + TypeScript + Tailwind + Framer Motion ব্যবহার হচ্ছে। ব্যাকএন্ডের জন্য পরিকল্পনা হলো Supabase (PostgreSQL + Auth + Realtime + Storage), Prisma ORM দিয়ে টাইপ-সেফ ডেটাবেস অ্যাক্সেস, Vercel Domains API দিয়ে কাস্টম ডোমেইন স্বয়ংক্রিয়ভাবে যুক্ত করা, Upstash Redis দিয়ে ক্যাশিং, এবং bKash/Nagad/Stripe দিয়ে পেমেন্ট। SMS/WhatsApp দিয়ে নোটিফিকেশন এবং থার্মাল প্রিন্টার দিয়ে কিচেন টিকিট/রিসিট প্রিন্ট হবে।

3. Current Implementation Status

This is important context for anyone (human or AI agent) picking up this codebase:

🟢 বাংলা সারাংশ: এই মুহূর্তে সব ৮টি UI সারফেস (ল্যান্ডিং, প্ল্যাটফর্ম-অ্যাডমিন, ড্যাশবোর্ড, টেবিল মেনু, কিচেন, ওয়েটার, রাইডার, প্রোমো) সম্পূর্ণভাবে ডিজাইন ও তৈরি করা হয়েছে, শুধু মক ডেটা এবং localStorage দিয়ে চলছে — কোনো আসল ডেটাবেস, পেমেন্ট গেটওয়ে বা রিয়েলটাইম সার্ভার এখনো যুক্ত হয়নি। এই ডকুমেন্টেশন সেই পরবর্তী ধাপের (ব্যাকএন্ড) জন্য একটি সম্পূর্ণ টেকনিক্যাল ব্লুপ্রিন্ট।

4. High-Level Architecture Diagram

                                   ┌───────────────────────────┐
                                   │        Vercel Edge         │
                                   │  (Next.js 16 App Router)   │
                                   └──────────────┬─────────────┘
                                                  │
                     ┌────────────────────────────┼────────────────────────────┐
                     │                            │                            │
             restaurant-os.com           swadh-ghar.restaurant-os.com   menu.kacchibhai.com
             (main platform domain)      (tenant subdomain)             (tenant custom domain,
                     │                            │                      CNAME → Vercel, verified
                     ▼                            ▼                      via Vercel Domains API)
          ┌─────────────────────┐      ┌─────────────────────────┐
          │   src/middleware.ts  │◄─────┤   Host header inspected  │
          │  (subdomain/domain   │      │   on every request        │
          │   resolution)        │      └─────────────────────────┘
          └──────────┬───────────┘
                     │ rewrites URL internally to
                     │ /[locale]/tenants/[tenant]/...
                     ▼
     ┌───────────────────────────────────────────────────────────────┐
     │                     Next.js App Router                        │
     │  (platform)/            → landing page + platform-admin        │
     │  tenants/[tenant]/      → dashboard, table, kitchen, waiter,   │
     │                           rider, promo                         │
     └───────────────────────────┬───────────────────────────────────┘
                                  │  Server Actions / Route Handlers
                                  ▼
                     ┌─────────────────────────────┐
                     │   Prisma Client (typed ORM)  │
                     └──────────────┬──────────────┘
                                    ▼
                     ┌─────────────────────────────┐
                     │  Supabase Postgres (RLS-on)  │──── Supabase Auth (staff/customer sessions)
                     │  tenants, orders, menu, ...  │──── Supabase Realtime (order/KDS channels)
                     └──────────────┬──────────────┘──── Supabase Storage (menu images, branding)
                                    │
        ┌───────────────────────────┼───────────────────────────┐
        ▼                           ▼                           ▼
┌───────────────┐        ┌───────────────────┐        ┌─────────────────────┐
│ Upstash Redis  │        │ bKash/Nagad/Stripe │        │ SMS/WhatsApp gateway │
│ (cache + rate  │        │ (payment IPN/      │        │ (order status push)  │
│  limiting)     │        │  webhooks)         │        └─────────────────────┘
└───────────────┘        └───────────────────┘

🟢 বাংলা সারাংশ: প্রতিটি রিকোয়েস্ট প্রথমে middleware.ts-এ যায়, যেখানে হোস্ট হেডার (subdomain বা custom domain) দেখে বোঝা হয় কোন tenant-এর জন্য রিকোয়েস্ট, তারপর সেটা ভেতরে ভেতরে /tenants/[tenant]/... রুটে rewrite হয়। এরপর Prisma দিয়ে Supabase Postgres-এ ডেটা অ্যাক্সেস হয় (RLS দিয়ে tenant আলাদা করা), Supabase Realtime দিয়ে লাইভ আপডেট, Redis দিয়ে ক্যাশ/রেট-লিমিট, এবং পেমেন্ট/SMS গেটওয়ে বাইরের সার্ভিস হিসেবে যুক্ত থাকবে।

5. Core Personas & Surfaces

🟢 বাংলা সারাংশ: প্ল্যাটফর্মে মোট ৯টি ভিন্ন ইউজার-টাইপ/সারফেস আছে — সম্ভাব্য রেস্টুরেন্ট মালিকদের জন্য ল্যান্ডিং পেজ, প্ল্যাটফর্ম অ্যাডমিনদের জন্য কনসোল, রেস্টুরেন্ট মালিকদের ড্যাশবোর্ড, কাস্টমারদের টেবিল মেনু, কিচেন স্টাফদের KDS, ওয়েটার অ্যাপ, রাইডার অ্যাপ, প্রোমো ল্যান্ডিং পেজ, এবং পিকআপ কাউন্টার টিভি স্ক্রিন।

6. Core Modules Summary

• Multi-Tenancy Engine — subdomain/custom-domain resolution, tenant context propagation, per-tenant branding (logo, colors, fonts) rendered via CSS variables injected at the layout level.
• Platform Admin Suite — tenant CRUD, dynamic subscription plan builder (with a feature catalog picker), granular feature flags (global + per-tenant override, plan-scoped whitelist), VIP billing overrides, automated PDF invoicing + mock email, "View as Restaurant" impersonation, platform-wide audit log, support tickets, roadmap showcase.
• Restaurant Dashboard — menu builder (categories, items, variants, modifiers), live order board, table management + QR generation, POS/billing, staff management + RBAC, analytics (BCG matrix, revenue trends, cohort/retention), inventory, CRM, reservations, promo campaign builder with drag-and-drop landing page CMS, settings (branding, domains, hours).
• Customer Digital Menu — dynamic per-table QR resolution, category browsing, allergy/dietary filter engine, cart with live group/shared-cart sync, split-bill, QR pay-at-table, post-bill spin-wheel gamification, abandoned-cart nudges.
• Kitchen Display System (KDS) — real-time ticket queue, station routing (grill/fry/drinks/dessert), prep-time SLAs, bump/recall actions.
• Waiter App — table status board, order assist, service requests, split-bill assistance.
• Rider App — delivery queue, live location, proof-of-delivery, earnings summary.
• Promo Engine — campaign-scoped QR codes, dedicated landing pages, revisit links so a customer can re-order from the same promo later, "how it works" explainer, drag-and-drop landing designer.

🟢 বাংলা সারাংশ: প্ল্যাটফর্মের মূল মডিউলগুলো হলো — মাল্টি-টেন্যান্সি ইঞ্জিন, প্ল্যাটফর্ম অ্যাডমিন স্যুট, রেস্টুরেন্ট ড্যাশবোর্ড, কাস্টমার ডিজিটাল মেনু, কিচেন ডিসপ্লে সিস্টেম, ওয়েটার অ্যাপ, রাইডার অ্যাপ, এবং প্রোমো ইঞ্জিন — প্রতিটি নিজস্ব ডেটা মডেল ও ফ্লো নিয়ে কাজ করে কিন্তু একই কোডবেস ও ডেটাবেস শেয়ার করে।

7. Related Documents

🟢 বাংলা সারাংশ: এই ডকুমেন্টটি বাকি ১১টি ডকুমেন্টের একটি হাই-লেভেল ভূমিকা মাত্র। প্রতিটি বিষয়ের বিস্তারিত টেকনিক্যাল স্পেসিফিকেশন উপরের টেবিলে লিংক করা নিজ নিজ ডকুমেন্টে পাওয়া যাবে।