Skip to content

POS Adapters

The POS Adapters service integrates SMACKZ with point-of-sale systems. Currently, it supports Clover POS, enabling restaurants to sync menus, orders, and payments between SMACKZ and their physical Clover terminals.

Tech Stack

Component Technology
Backend Node.js 20+, TypeScript, Fastify
Database PostgreSQL 16 via Drizzle ORM
Validation Zod
Frontend React 18, Tailwind CSS, React Query
Deployment Docker Compose / Control Plane

Features

  • OAuth integration with Clover for multi-tenant merchant connections
  • Menu sync -- Pull categories and items from Clover into SMACKZ
  • Order sync -- Push SMACKZ orders to Clover POS
  • Payment processing with PCI compliance
  • Credit card storage for future payments
  • Webhook support for real-time Clover updates

Multi-Tenant Connection Flow

  1. Restaurant owner enters their SMACKZ Restaurant ID and Clover Merchant ID
  2. System generates a Clover OAuth URL targeting the specific merchant (getAuthorizationUrl(merchantId?) appends merchant_id to OAuth params if supplied)
  3. Owner completes OAuth authorization
  4. System fetches merchant details from Clover API automatically — POST complete-onboarding calls cloverApiService.getMerchantDetails(accessToken) to pull the merchant name from /v3/merchants/self if merchantName is omitted (falls back to "Unknown Merchant")
  5. Mapping is created linking the SMACKZ restaurant to the Clover merchant

Each SMACKZ restaurant connects to a specific Clover merchant, supporting true multi-tenancy with reduced manual input and accurate Clover-sourced data.

Key Endpoints

Endpoint Method Purpose
/api/v1/clover/auth/connect GET Generate Clover OAuth URL
/api/v1/clover/auth/callback GET Handle OAuth callback
/api/v1/clover/restaurants/sync POST Sync restaurant data
/api/v1/clover/restaurants/{id}/menu/sync POST Sync full menu
/api/v1/clover/restaurants/{id}/orders POST Create order in Clover
/api/v1/clover/webhooks POST Handle Clover webhooks

Project Structure

clover-adapter/
├── src/                  # Backend source
│   ├── api/              # REST routes and schemas
│   ├── config/           # App configuration
│   ├── db/               # Database schemas
│   ├── repositories/     # Data access layer
│   ├── services/         # Business logic
│   └── types/            # TypeScript definitions
├── frontend/             # React frontend
├── drizzle/              # Database migrations
├── docker-compose.yml    # Docker setup
└── Dockerfile            # Backend container

Local Development

cd clover-adapter
npm install
cp env.example .env
# Edit .env with Clover credentials
npm run dev              # Backend at http://localhost:3000
cd frontend && npm start # Frontend at http://localhost:3000

Key Files

  • Smackz-POS-Adapters/CLAUDE.md -- Branch and commit rules
  • Smackz-POS-Adapters/env.example -- Required environment variables
  • Smackz-POS-Adapters/docker-compose.yml -- Docker setup