Store Provisioning

Each store in the POS system operates with its own local database and applications. This guide explains how to create a new store in HQ, generate its sync credentials, and configure the store-side applications to connect back to headquarters.

Creating a Store in HQ Manager

Log into the HQ Manager and navigate to Stores. Click "Add Store" and fill in the required fields: a unique store code (e.g., STORE-001), the store name, and the address. The store code is used throughout the system to identify transactions, inventory, and reports originating from this location. Choose a code that is short, memorable, and consistent with your naming convention.

After saving the store, it appears in the store list with a status of "Pending Provisioning". No data will sync to the store until provisioning is complete.

Generating the Sync Token

From the store detail page in HQ Manager, click "Generate Sync Token". This produces a one-time-use token that the store application will use to authenticate its initial connection to HQ. The token is displayed once -- copy it immediately and store it securely. If you lose the token before using it, you can revoke it and generate a new one.

The sync token encodes the store ID, the HQ server address, and a cryptographic secret. When the store application presents this token during its first sync, HQ verifies the token, registers the store as "Active", and begins transmitting the full product catalog, departments, tax rates, and user assignments.

Setting Up the Store Database

On the store machine, install PostgreSQL and create a local database:

# Using Docker
docker run -d --name pos-store-db \
  -e POSTGRES_USER=pos \
  -e POSTGRES_PASSWORD=pos \
  -e POSTGRES_DB=pos_store \
  -p 5432:5432 \
  postgres:16

# Run store migrations
cd apps/store-server
cargo run -- migrate

The store database schema mirrors the HQ schema for synchronized tables (products, departments, tax rates, users) and adds store-specific tables for sales transactions, register sessions, and local inventory.

Configuring Store Applications

Create or edit the .env file in the apps/store-server directory:

DATABASE_URL=postgres://pos:pos@localhost:5432/pos_store
REDIS_URL=redis://localhost:6379
STORE_SERVER_PORT=3000
HQ_SYNC_URL=wss://hq.example.com:3001
SYNC_TOKEN=paste-your-token-here

Start the store server with cargo run. On first launch, it will present the sync token to HQ, receive the initial data payload, and populate the local database. This initial sync may take a few minutes depending on the size of your product catalog.

Verifying the Connection

Once the store server is running and the initial sync completes, check the store status in HQ Manager. It should change from "Pending Provisioning" to "Active", and you will see the last sync timestamp. On the store side, the Store Manager dashboard will show the product count and confirm the connection to HQ.

You can now open the POS Terminal application on the store machine and begin processing sales. Employees assigned to this store in HQ Manager will be able to log in with their PINs.