Skip to main content

System Architecture

The UCH Ecosystem relies on a hybrid Offline-First / Cloud-Synced architecture designed to provide 100% uptime for local restaurant operations while offering global visibility via the cloud.

High-Level Topology​

graph TD
    subgraph Local Restaurant Network
        POS[Desktop POS - Electron]
        DB_LOCAL[(Local MongoDB)]
        KDS[Kitchen Display System]
        WA[Waiter App - React Native / PWA]
        PR[Printers]
        
        POS <--> DB_LOCAL
        WA -- WiFi --> POS
        POS -- IP/USB --> PR
        POS <--> KDS
    end

    subgraph Cloud Infrastructure (Vercel + Atlas)
        API[UCH Platform - Next.js API]
        DB_CLOUD[(Cloud MongoDB Atlas)]
        WEB[Web Dashboard]
        
        WEB <--> API
        API <--> DB_CLOUD
    end

    subgraph External Aggregators
        UP[UrbanPiper Webhooks]
    end

    POS -- Sync Worker --> API
    UP -- Webhooks --> API

1. On-Premise POS (uch-desktop)​

  • Framework: Built using Electron + Next.js (React) to run as a native Windows application.
  • Database: Runs a local MongoDB instance on the host machine.
  • Event Bus: Uses a custom uch_shortcut CustomEvent bus for keyboard-driven global navigation and page-level actions.
  • State Management: Uses Zustand for global state and local React Contexts for complex modules like the Menu Picker.

2. Cloud CRM (uch-platform)​

  • Framework: Next.js (App Router) deployed on Vercel.
  • API Routing: Implements a catch-all route src/app/api/v1/[[...path]]/route.ts which acts as a dispatcher for 191+ internal handlers ported from Python.
  • Database: MongoDB Atlas cluster.
  • Webhooks: Exposes endpoints to receive Order Status and Menu Sync callbacks from UrbanPiper.

3. Sync Mechanism​

The synchronization is primarily driven by the Desktop POS polling and pushing to the Cloud API when an active internet connection is detected.

  • All MongoDB documents use unique UUIDs or compounded tenantId_outletId_localId composite keys to prevent collision.
  • A local sync_queue collection tracks mutations that need to be pushed to the cloud.

4. Hardware Integration​

The Desktop POS handles raw thermal printing using the receiptline library or native OS print drivers to talk directly to network (IP) or USB ESC/POS printers. Waiter App requests are relayed through the Desktop POS to trigger physical KOT prints in the kitchen.