Skip to content

Parwaiz-Dev/AuraOS

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

17 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

🍽️ AuraOS β€” Restaurant Management Platform

TypeScript React 18 Node.js 18 Express PostgreSQL 15 Socket.io Docker Tailwind CSS

A multi-tenant restaurant POS platform supporting 6 restaurant types with real-time kitchen display, QR ordering, WhatsApp & Zomato integrations, and inventory management.


πŸ“‘ Table of Contents


✨ Highlights

🏒 Multi-tenant architecture 🏷️ 6 restaurant types ⚑ Real-time updates (Socket.io)
πŸ“± QR ordering πŸ–₯️ Kitchen Display System πŸ”’ Customer Token Display
πŸ“¦ Inventory management πŸ’° Payment collection πŸ” Role-based access control
πŸ›‘οΈ Super Admin platform 🐳 Docker support

πŸš€ Demo

Live Endpoints

Service URL Auth
Staff Portal http://localhost:3001 Login
Backend API http://localhost:3000/api/v1 JWT
Customer Ordering http://localhost:3001/customer?slug=demo-kitchen Public
Health Endpoint http://localhost:3000/api/v1/health Public

Demo Credentials

Email:    admin@demo-kitchen.local
Password: demo123

Run npm run migrate to seed the demo restaurant with sample data.


πŸ“– Overview

AuraOS is a multi-tenant Point of Sale system built for restaurants of every shape and size. A single superadmin can manage multiple restaurants, each with its own menu, tables, staff, features, and subscription plan β€” all from one dashboard.

Six Restaurant Types, One Platform

Type Description Best For
🍽️ Full Service Table service, waiters, QR ordering, full menu Fine dining, family restaurants
πŸ” QSR Simple Counter-ordering, quick turnaround, kitchen display Fast-food, single-location quick-service
🏒 QSR Chain Multi-outlet QSR with centralized management Franchises, chain restaurants
β˜• CafΓ© Light menu, QR ordering, no waiter app Coffee shops, bakeries, casual cafΓ©s
🏭 Cloud Kitchen Delivery-only, no dine-in, Zomato integration Ghost kitchens, delivery brands
πŸ”€ Hybrid Mix of dine-in + delivery + takeaway Modern restaurants, food courts

Each type pre-configures the right feature flags, dashboard cards, and navigation items β€” so restaurants only see what they need.


βš™οΈ Features

πŸ” Authentication

  • JWT access tokens (15 min) + refresh tokens (7 days) with automatic renewal
  • bcryptjs password hashing
  • Zod schema validation on all inputs
  • Rate limiting on login and registration endpoints
  • Password reset flow with email tokens

πŸ“‹ Orders

  • Create and manage orders with a slide-over cart panel
  • Supports Dine-In, Parcel, and Online order types
  • Order status pipeline: CREATED β†’ ACCEPTED β†’ PREPARING β†’ READY β†’ COMPLETED
  • Running tabs β€” active orders persist on tables until paid
  • Auto-incrementing daily token numbers for parcel/pickup orders
  • Programmatic KOT and receipt printing via window.print()

πŸͺ‘ Tables

  • Visual floor plan with grid/column layout of sections and tables
  • Color-coded table states: Available, Occupied, Reserved, Maintenance
  • Click any table to view the running order, add items, or collect payment
  • Generate and print QR codes per table

πŸ–₯️ Kitchen Display

  • Real-time order board via Socket.io β€” orders appear as they're placed
  • Sort by wait time or priority
  • Mark individual items as done; order auto-completes when all items are ready
  • Delay alerts when orders exceed preparation thresholds
  • Full-screen mode for dedicated kitchen monitors

πŸ“± QR Ordering

  • Customers scan a QR code, browse the menu, and place orders β€” no login needed
  • Restaurant slug system (/customer?slug=restaurant-name)
  • Orders automatically linked to the correct table
  • WhatsApp share for takeaway/pre-order scenarios

πŸ’° Payments

  • Cash, UPI, Card, and Razorpay online payments
  • Collect full or partial payments against running orders
  • Filterable transaction history (Paid, Pending, Refunded)
  • Razorpay webhook receiver for automated payment confirmation

πŸ“¦ Inventory

  • Track ingredients and supplies with unit, quantity, and reorder thresholds
  • Low-stock alerts on the dashboard
  • Full audit trail of stock adjustments with reason tracking
  • Background job syncs inventory every 60 seconds

πŸ“Š Reports

  • Area chart showing daily revenue trends (7/14/30 day views)
  • Bar chart of best-selling items by quantity
  • Pie chart of sales by category distribution
  • Key metrics: today's revenue, total orders, average order value, active tables

πŸ‘₯ Users & Roles

  • 6 roles: Super Admin, Admin, Manager, Staff, Waiter, Kitchen
  • Add, edit, deactivate staff accounts per restaurant
  • Sidebar navigation dynamically filtered by role and restaurant features

πŸ§‚ Modifiers

  • Modifier groups: toppings, add-ons, spice levels
  • Attach groups to menu items with optional/min/max selection rules
  • Section organization for menus (e.g., "Breakfast Menu", "Lunch Menu")

🏷️ Restaurant Types

  • Centralized type definitions in restaurantTypes.ts
  • Per-type configs: nav visibility, dashboard cards, setup wizard steps, default features
  • Selecting a type during creation auto-sets sensible feature defaults

πŸ›‘οΈ Super Admin

  • Multi-tenant dashboard β€” view all restaurants, status, and metrics
  • Create new restaurants with type selection, feature presets, and admin account
  • Toggle individual features per restaurant (8 toggleable features)
  • Suspend and reactivate restaurant accounts
  • Organization groups for chain/franchise management with aggregate metrics
  • Built-in support ticket system and contact inquiry management

πŸ“ˆ Monitoring

  • Real-time system health, uptime, memory, and active connections
  • Error log with stack traces and request context
  • Health check endpoints: /api/v1/health, /api/v1/health/live, /api/v1/health/ready
  • Optional Sentry integration for production error tracking

πŸ“ž Book Demo Flow

  • Public landing page with restaurant type showcase, pricing tiers, FAQ, and contact form
  • Self-registration onboarding flow for restaurant owners
  • Contact inquiries with status tracking in the superadmin dashboard

πŸ—οΈ Architecture

High-Level System Architecture

graph TB
    subgraph Frontend["Frontend (Ports 3001 & 3002)"]
        SP[Staff Portal<br/>React 18 + Vite]
        WA[Waiter App<br/>React PWA]
        CUST[Customer QR Ordering<br/>React Page]
    end

    subgraph Backend["Backend (Port 3000)"]
        API[REST API<br/>Express 4]
        WS[WebSocket<br/>Socket.io 4]
        JOBS[Background Jobs<br/>Delay Detector + Inventory Sync]
        MON[Monitoring<br/>Health + Metrics + Errors]
    end

    subgraph Integrations["External Integrations"]
        ZOM[Zomato Webhook]
        WAPP[WhatsApp Webhook]
        RZP[Razorpay Webhook]
        EMAIL[SMTP Email]
    end

    subgraph Data["Data Layer"]
        DB[(PostgreSQL 15)]
    end

    SP -->|Axios| API
    WA -->|Axios| API
    CUST -->|Axios| API
    SP -->|Socket.io| WS
    WA -->|Socket.io| WS

    ZOM -->|Webhook| API
    WAPP -->|Webhook| API
    RZP -->|Webhook| API
    API -->|Nodemailer| EMAIL

    API --> DB
    JOBS --> DB
    WS -->|Event Push| SP
    WS -->|Event Push| WA
Loading

Layered Architecture (Frontend β†’ Database)

graph TD
    subgraph Frontend["Frontend"]
        REACT[React Component]
        CTX[Context / Hooks]
        AX[Axios Client]
    end

    subgraph Backend["Backend"]
        direction TB
        ROUTE[Route Layer<br/>Validation + Auth Middleware]
        CTRL[Controller<br/>Request/Response Handling]
        SVC[Service Layer<br/>Business Logic]
        REPO[Repository Layer<br/>Raw SQL Queries]
    end

    DB[(PostgreSQL)]

    REACT --> CTX --> AX
    AX -->|HTTP Request| ROUTE
    ROUTE -->|Validated| CTRL
    CTRL -->|Delegates| SVC
    SVC -->|Queries| REPO
    REPO -->|pg Pool| DB
    DB -->|Result Rows| REPO
    REPO -->|Typed Entities| SVC
    SVC -->|Domain Objects| CTRL
    CTRL -->|JSON Response| AX
    AX -->|Response Data| CTX -->|State Update| REACT
Loading

JWT Authentication Flow

sequenceDiagram
    participant Client
    participant Server
    participant DB

    Client->>Server: POST /api/v1/auth/login { email, password }
    Server->>DB: SELECT user WHERE email
    DB-->>Server: User row (hashed password)
    Server->>Server: bcrypt.compare(password, hash)
    Server->>Server: Generate JWT (15min) + Refresh Token (7d)
    Server-->>Client: { token, refreshToken, user }

    Note over Client,Server: Token expires after 15 minutes

    Client->>Server: POST /api/v1/auth/refresh { refreshToken }
    Server->>DB: Verify refresh token
    Server->>Server: Generate new JWT + Refresh Token
    Server-->>Client: { token, refreshToken }
Loading

Real-time Kitchen Order Flow (Socket.io)

sequenceDiagram
    participant Staff as Staff POS
    participant Server as Backend
    participant Kitchen as Kitchen Display

    Staff->>Server: POST /api/v1/orders { items, table_id }
    Server->>Server: Validate, create order, insert items
    Server->>Server: Broadcast 'ORDER_CREATED'
    Server-->>Kitchen: Socket.io β†’ ORDER_CREATED
    Kitchen->>Kitchen: Add order to display board

    Kitchen->>Server: PATCH /api/v1/orders/:id/items/:itemId/status
    Server->>Server: Update item status, check if all done
    Server->>Server: Broadcast 'ORDER_ITEM_STATUS'
    Server-->>Staff: Socket.io β†’ ORDER_ITEM_STATUS

    Server->>Server: All items done β†’ auto-set order to READY
    Server->>Server: Broadcast 'ORDER_STATUS_CHANGED'
    Server-->>Staff: Socket.io β†’ ORDER_STATUS_CHANGED
    Server-->>Kitchen: Socket.io β†’ ORDER_STATUS_CHANGED
Loading

Multi-Tenant Architecture

graph TB
    SA[Super Admin] -->|Manages| ALL[All Restaurants]
    ALL --> R1[Restaurant A<br/>Full Service]
    ALL --> R2[Restaurant B<br/>QSR Chain]
    ALL --> R3[Restaurant C<br/>Cloud Kitchen]

    R1 --> U1[Admin A]
    R2 --> U2[Admin B]
    R3 --> U3[Admin C]

    R1 --> F1[Features: Kitchen, QR, Waiter, ...]
    R2 --> F2[Features: Kitchen, Inventory, Chain, ...]
    R3 --> F3[Features: Kitchen, Zomato, ...]

    U1 -->|Scoped to| R1
    U2 -->|Scoped to| R2
    U3 -->|Scoped to| R3

    SA -->|Organization Groups| OG[Franchise Group]
    OG --> R2
    OG --> R4[Restaurant D<br/>Same Chain]
Loading

πŸ› οΈ Tech Stack

Backend

Category Technology Purpose
Runtime Node.js 18+ JavaScript runtime
Language TypeScript (strict) Type safety
Framework Express 4 HTTP server, routing, middleware
Database PostgreSQL 15 Relational data store
Query pg (raw SQL) Parameterized queries, no ORM
Auth JWT + bcryptjs Access/refresh tokens, password hashing
Validation Zod Schema-based input validation
Real-time Socket.io 4 WebSocket push to kitchen/client
Payments Razorpay Payment gateway
Email Nodemailer Transactional emails
Rate Limiting express-rate-limit API abuse prevention
Security Helmet, CORS HTTP security headers, cross-origin
Logging Morgan HTTP request logging
Testing Jest + Supertest Unit and integration tests
Container Docker Compose PostgreSQL database container

Frontend

Category Technology Purpose
Framework React 18 UI component library
Build Vite Fast dev server and bundler
Language TypeScript (strict) Type safety
Styling Tailwind CSS 3 Utility-first CSS framework
Charts Recharts Revenue, top items, pie charts
Routing React Router v6 Client-side routing
HTTP Axios API client with interceptors
WebSocket Socket.io Client Real-time order updates
Notifications react-hot-toast Toast notifications
UI Primitives @headlessui/react Accessible modals, transitions
Icons @heroicons/react + lucide-react SVG icon libraries
Date date-fns Date formatting and math
PWA vite-plugin-pwa + Workbox Service worker, offline support
Testing Vitest + Testing Library Component and hook tests

πŸ“Έ Screenshots

Screenshots are stored in docs/screenshots/. See docs/screenshots/README.md for capture instructions.

🌐 Public Pages

Landing Page
Landing Page
Marketing landing page with restaurant type showcase, pricing tiers, FAQ, and contact form

πŸ“Š Staff Portal

Dashboard Orders
Dashboard Orders
Revenue charts, metrics cards, setup wizard, and quick actions Order management with status tabs, filtering, and slide-over cart
Tables Kitchen Display
Tables Kitchen Display
Visual floor plan with color-coded table states and QR code generation Real-time order board with status controls, delay alerts, and full-screen mode
Reports Menu
Reports Menu
Revenue trends, top-selling items, category distribution with interactive charts Category and item management with pricing, modifiers, and availability toggles

πŸ’» Installation

Prerequisites

Tool Version Check Notes
Node.js 18+ node -v Runtime for all services
npm 9+ npm -v Comes with Node.js
PostgreSQL 14+ psql --version Or use Docker (see below)

Quick Start with Docker

# Start PostgreSQL
docker compose up -d

Creates PostgreSQL 15, Redis 7, backend, AI analytics, frontend, and nginx containers. PostgreSQL is mapped to host port 5433 (container port 5432).

1. Clone & Install

git clone https://github.com/your-org/auraos.git
cd auraos

# Install backend dependencies
npm install

# Install staff portal dependencies
cd client && npm install && cd ..

# Install waiter app dependencies
cd apps/waiter && npm install && cd ../..

2. Configure Environment

cp .env.example .env

Edit .env with the minimum required values:

DATABASE_URL=postgresql://auraos_user:auraos_password@localhost:5433/auraos
JWT_SECRET=your_random_secret_at_least_32_characters_long
JWT_REFRESH_SECRET=another_random_secret_at_least_32_characters
CORS_ORIGIN=http://localhost:3001,http://localhost:3002
# Required by docker-compose.yml for the postgres container:
POSTGRES_PASSWORD=auraos_password

Razorpay, WhatsApp, Zomato, SMTP, and Sentry are optional β€” defaults use cash-only payments, console email, and console monitoring.

3. Run Migrations

npm run migrate

Seeds a demo restaurant with sample data.

4. Start the Services

Open 3 terminals:

Terminal Command Port What
1 (root) npm run dev 3000 Backend API + Socket.io + Background Jobs
2 (client/) npm run dev 3001 Staff Portal (React PWA)
3 (apps/waiter/) npm run dev 3002 Waiter App (React PWA)

URLs

Service URL Auth
Backend API http://localhost:3000/api/v1 JWT
Health Check http://localhost:3000/api/v1/health Public
Staff Portal http://localhost:3001 Login
Kitchen Display http://localhost:3001/kitchen Login
Customer QR Ordering http://localhost:3001/customer?slug=demo-kitchen Public
Waiter App http://localhost:3002 Login

Running Tests

# Backend tests
npm test

# Frontend tests
cd client && npm test

πŸ—„οΈ Database

AuraOS uses raw SQL with parameterized queries via the pg driver β€” no ORM. All queries are hand-written in the repository layer.

Migration History

# File Purpose
001 001_enums.sql Custom PostgreSQL enum types (order status, payment methods, user roles, restaurant types)
002 002_core.sql Core tables: users, restaurants, tables, sections
003 003_menu.sql Menu categories, items, and pricing
004 004_orders.sql Orders, order items, order status tracking
005 005_supporting.sql Payments, inventory items, inventory transactions
006 006_seed.sql Demo data: restaurant, admin user, sample menu, tables
007 007_qr_mode.sql QR ordering mode and public menu endpoints
008 008_password_reset.sql Password reset tokens and flow
009 009_inventory_history.sql Inventory adjustment history with reason tracking
010 010_zomato_mapping.sql Zomato order mapping and webhook storage
011 011_subscriptions.sql Subscription plans, invoices, and billing
012 012_restaurant_features.sql Feature flags per restaurant (8 toggleable features)
013 013_missing_indexes.sql Performance indexes on high-traffic columns
014 014_admin_inquiries_support.sql Contact inquiries and support ticket system
015 015_refresh_tokens.sql Refresh token storage and rotation
016 016_restaurant_gst.sql GST number and tax configuration per restaurant
017 017_restaurant_type_qsr_sections.sql Menu sections for QSR and Full Service types
018 018_orders_token_number.sql Daily auto-incrementing token numbers for orders
019 019_modifiers.sql Modifier groups, options, and order item modifiers
020 020_organization_groups.sql Multi-outlet organization groups for chain management

Key Schema Decisions

  • No ORM β€” Every query is hand-written SQL for full control over query plans and performance
  • Parameterized Queries β€” All user input uses $1, $2, ... placeholders, eliminating SQL injection
  • Repository Pattern β€” Each module has a dedicated repository class encapsulating all database access
  • Enum Types β€” PostgreSQL native enums for order status, payment methods, user roles, and restaurant types
  • Foreign Keys β€” All relationships enforced with FK constraints and cascading deletes
  • Indexes β€” Strategic indexes on restaurant_id, status, created_at, and FK columns

πŸ“ Project Structure

πŸ“‚ Backend β€” src/
src/
β”œβ”€β”€ app.ts                        # Express app setup, middleware, route mounting
β”œβ”€β”€ server.ts                     # HTTP server, Socket.io init, graceful shutdown
β”œβ”€β”€ config/
β”‚   β”œβ”€β”€ database.ts               # PostgreSQL pool (pg, max 20 connections)
β”‚   β”œβ”€β”€ env.ts                    # Environment variable validation (Zod)
β”‚   β”œβ”€β”€ email.ts                  # Nodemailer transport configuration
β”‚   └── payments.ts               # Payment gateway config (Razorpay)
β”œβ”€β”€ modules/
β”‚   β”œβ”€β”€ admin/                    # Superadmin routes (create restaurant, inquiries, tickets)
β”‚   β”œβ”€β”€ auth/                     # Login, register, JWT, refresh tokens
β”‚   β”œβ”€β”€ restaurants/              # Restaurant CRUD, sections, features, stats
β”‚   β”œβ”€β”€ tables/                   # Table management, sections, status
β”‚   β”œβ”€β”€ menu/                     # Categories, items, availability
β”‚   β”œβ”€β”€ modifiers/                # Modifier groups, options, attachment to items
β”‚   β”œβ”€β”€ orders/                   # Order lifecycle, items, status pipeline
β”‚   β”œβ”€β”€ payments/                 # Payment recording, gateway integration, webhooks
β”‚   β”œβ”€β”€ inventory/                # Stock tracking, adjustments, history
β”‚   β”œβ”€β”€ reports/                  # Revenue, top items, category distribution
β”‚   β”œβ”€β”€ users/                    # Staff management, roles
β”‚   β”œβ”€β”€ onboarding/               # Restaurant self-registration flow
β”‚   β”œβ”€β”€ subscriptions/            # Plans, invoices, billing
β”‚   β”œβ”€β”€ organizations/            # Multi-outlet groups for chain management
β”‚   └── public/                   # Public endpoints (QR ordering, no auth)
β”œβ”€β”€ integrations/
β”‚   β”œβ”€β”€ zomato/                   # Zomato webhook receiver, order mapping
β”‚   └── whatsapp/                 # WhatsApp Business API webhook, order parsing
└── shared/
    β”œβ”€β”€ errors/                   # AppError, NotFoundError, ValidationError classes
    β”œβ”€β”€ middleware/                # authenticate, authorize, errorHandler, rateLimiter
    β”œβ”€β”€ jobs/                     # Background jobs (delay detector, inventory sync)
    └── monitoring/               # Health checks, metrics, error capture
πŸ“‚ Frontend β€” client/src/
client/src/
β”œβ”€β”€ pages/
β”‚   β”œβ”€β”€ Dashboard.tsx             # Revenue charts, metrics, setup wizard
β”‚   β”œβ”€β”€ Orders.tsx                # Order management with tabs
β”‚   β”œβ”€β”€ Tables.tsx                # Table floor plan and status management
β”‚   β”œβ”€β”€ Kitchen.tsx               # Kitchen display system
β”‚   β”œβ”€β”€ Menu.tsx                  # Menu categories and items CRUD
β”‚   β”œβ”€β”€ Payments.tsx              # Payment history and collection
β”‚   β”œβ”€β”€ Inventory.tsx             # Inventory tracking and adjustments
β”‚   β”œβ”€β”€ Reports.tsx               # Analytics dashboard with charts
β”‚   β”œβ”€β”€ Users.tsx                 # Staff management
β”‚   β”œβ”€β”€ Features.tsx              # Feature flag toggles
β”‚   β”œβ”€β”€ QRSettings.tsx            # QR code generation and settings
β”‚   β”œβ”€β”€ OwnerDashboard.tsx        # Superadmin multi-tenant dashboard
β”‚   β”œβ”€β”€ MultiOutlet.tsx           # Organization group management
β”‚   β”œβ”€β”€ Monitoring.tsx            # System health and error monitoring
β”‚   β”œβ”€β”€ Onboarding.tsx            # Restaurant self-registration
β”‚   β”œβ”€β”€ LandingPage.tsx           # Public landing/marketing page
β”‚   β”œβ”€β”€ Login.tsx                 # Authentication
β”‚   β”œβ”€β”€ CustomerApp.tsx           # Customer QR ordering page
β”‚   └── NotFound.tsx              # 404 page
β”œβ”€β”€ components/
β”‚   β”œβ”€β”€ Layout.tsx                # App shell with sidebar navigation
β”‚   β”œβ”€β”€ OrderForm.tsx             # Order creation/editing slide-over
β”‚   β”œβ”€β”€ AddItemsModal.tsx         # Add items to existing order
β”‚   β”œβ”€β”€ PaymentForm.tsx           # Payment collection modal
β”‚   β”œβ”€β”€ PrintKOT.tsx              # Kitchen order ticket printer
β”‚   β”œβ”€β”€ PrintReceipt.tsx          # Customer receipt printer
β”‚   β”œβ”€β”€ Modal.tsx                 # Reusable modal component
β”‚   β”œβ”€β”€ ErrorBoundary.tsx         # React error boundary
β”‚   β”œβ”€β”€ ProtectedRoute.tsx        # Auth + role + superadmin route guard
β”‚   β”œβ”€β”€ SetupWizard.tsx           # Step-by-step onboarding wizard
β”‚   └── TableOrderPanel.tsx       # Table-level order management panel
β”œβ”€β”€ contexts/
β”‚   β”œβ”€β”€ AuthContext.tsx           # Auth state, login/logout, token refresh
β”‚   β”œβ”€β”€ FeaturesContext.tsx       # Feature flags, restaurant type, nav filtering
β”‚   └── SocketContext.tsx         # Socket.io connection management
β”œβ”€β”€ config/
β”‚   └── restaurantTypes.ts        # Type definitions, defaults, nav visibility, wizard steps
└── lib/
    └── utils.ts                  # Shared utility functions
πŸ“‚ Other Directories
β”œβ”€β”€ apps/waiter/                  # Waiter App (React PWA, standalone)
β”‚   β”œβ”€β”€ src/api/                  # API client and endpoints
β”‚   └── ...
β”œβ”€β”€ migrations/                   # SQL migration files (001-020)
β”œβ”€β”€ scripts/                      # Utility scripts
β”‚   β”œβ”€β”€ migrate.ts                # Migration runner
β”‚   β”œβ”€β”€ backup-db.ts              # Database backup
β”‚   β”œβ”€β”€ restore-db.ts             # Database restore
β”‚   β”œβ”€β”€ create-super-admin.ts     # CLI superadmin creation
β”‚   └── ...
β”œβ”€β”€ backups/                      # Database backup files
β”œβ”€β”€ docker-compose.yml            # PostgreSQL container
β”œβ”€β”€ .env.example                  # Environment template
β”œβ”€β”€ package.json                  # Backend dependencies and scripts
└── jest.config.js                # Backend test configuration

🧠 Key Design Decisions

1. Raw SQL, No ORM

Every database query is hand-written SQL with parameterized placeholders. This gives full control over query structure, joins, and indexes β€” no N+1 surprises from lazy-loading ORMs, no migration framework, no query builder DSL. Just SQL files and the pg driver.

2. Repository Pattern

Each module follows a strict three-layer architecture:

Route β†’ Controller β†’ Service β†’ Repository β†’ PostgreSQL
  • Routes β€” Define endpoints, apply middleware (auth, validation, rate limiting)
  • Controllers β€” Parse request, call service, format response
  • Services β€” Business logic, validation, orchestration
  • Repositories β€” Raw SQL queries, return typed entities

Business logic is testable without a database, and SQL changes don't leak into route handlers.

3. Feature Flags, Not Code Branches

Instead of if (restaurant.type === 'FULL_SERVICE') scattered throughout the codebase, features are toggleable flags. Navigation items, dashboard cards, and setup wizard steps are filtered by these flags. Selecting a restaurant type during creation auto-sets sensible defaults.

4. JWT + Refresh Token Authentication

  • Access Token β€” 15-minute expiry, sent in Authorization: Bearer header
  • Refresh Token β€” 7-day expiry, stored in database, used to get new access tokens
  • Auto-Refresh β€” The Axios interceptor detects 401 responses and automatically refreshes the token before retrying
  • Role Guards β€” ProtectedRoute checks user.role and user.isSuperAdmin before rendering protected pages

5. Socket.io for Real-Time Kitchen

Orders placed by staff appear instantly on the kitchen display without polling:

  • ORDER_CREATED β€” New order appears on the board
  • ORDER_STATUS_CHANGED β€” Order moves through CREATED β†’ ACCEPTED β†’ PREPARING β†’ READY β†’ COMPLETED
  • ORDER_ITEM_STATUS β€” Individual item marked done/undone
  • ORDER_DELAYED β€” Visual alert when order exceeds preparation threshold

6. Programmatic Printing

KOT (Kitchen Order Tickets) and receipts are printed via window.print() with @media print CSS. No external print libraries or browser extensions needed.

7. Multi-App Monorepo

Three separate applications share the same backend, each with its own package.json, tsconfig.json, and vite.config.ts:

App Directory Port
Staff Portal client/ 3001
Waiter App apps/waiter/ 3002
Backend API src/ 3000

8. Restaurant Type System

Six restaurant types are defined in restaurantTypes.ts with associated configs: NAV_TYPE_VISIBILITY, DASHBOARD_CARDS_BY_TYPE, SETUP_WIZARD_STEPS, and DEFAULT_FEATURES_BY_TYPE. This centralizes type-specific behavior in one config file instead of spreading conditionals across pages.


🚧 Future Improvements

  • Loyalty Program β€” Points-based customer loyalty with rewards and redemption
  • Customer Profiles β€” Order history, preferences, and saved payment methods per customer
  • Reservations β€” Table booking with time slots, capacity management, and confirmation flow
  • Swiggy Integration β€” Webhook receiver for Swiggy order push into the POS
  • AI Copilot β€” Smart menu suggestions, demand forecasting, and inventory optimization
  • Mobile App β€” Native iOS and Android apps for staff and customers
  • CI/CD Pipeline β€” Automated testing, linting, and deployment via GitHub Actions

πŸ“„ License

MIT License

Copyright (c) 2025 AuraOS

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

About

Multi-tenant restaurant management platform built with React, TypeScript, Node.js, Express, PostgreSQL, and Socket.io.

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages