Local setup

Each application is an independent repo with its own dependencies. You generally don’t need all four running to work on one, but the API is a dependency of the other three.

API (dg_smart_pos_api)

composer install
php artisan serve                  # API on :8000
composer dev                       # server + queue workers + Reverb WebSocket together

Database setup:

php artisan migrate                # central DB only
php artisan tenants:migrate        # all tenant DBs

Read this before running migrations, seeders, or tests

There’s a documented incident where a test run wiped the real local central database. See Conventions → Database safety before running anything that touches a database here, every time, not just once.

Queue workers, needed for background jobs (run the ones relevant to what you’re working on):

php artisan queue:work --tries=3 --timeout=90
php artisan queue:work central --queue=backups --tries=3 --timeout=90        # backup jobs
php artisan queue:work redis --queue=inventory-import --tries=2 --timeout=200 # CSV stock import
php artisan queue:work --queue=platform-migrations --tries=1 --timeout=3600   # platform migration backfills
php artisan reverb:start --debug   # WebSocket server

Linting and tests:

./vendor/bin/pint       # PHP linter / auto-fixer
php artisan test        # PHPUnit / Pest

POS frontend (dg_smart_pos_frontend)

Uses pnpm, not npm or yarn.

pnpm install
pnpm run dev        # SPA dev server on :3001
pnpm run build       # production build
pnpm run lint        # ESLint auto-fix
pnpm run test        # Vitest
pnpm run electron    # Electron dev app (wraps the SPA)

Needs VITE_TITAN_API pointing at the API (e.g. http://localhost:8000/api/), plus VITE_REVERB_* vars if you need live WebSocket updates locally.

On first run you’ll hit the tenant setup screen: enter a client code for a tenant that already exists in your central DB.

Admin (dg_smart_pos_admin)

pnpm install
pnpm run dev        # admin dev server on :3000
pnpm run build
pnpm run lint

Needs VITE_TITAN_API_URL pointing at the API (no trailing slash). No tenant setup step, admin never operates as a tenant.

Storefront (dg_smart_pos_storefront)

Astro + Preact + Tailwind, deployed to Cloudflare (see wrangler.toml).

pnpm install
pnpm run dev
pnpm run build

Storefront theming is driven by a theme_key per website (electronics or organics today) rather than by env var, see Storefront for how that works.

Electron desktop build

The desktop app wraps the POS frontend SPA. Entry point: dg_smart_pos_frontend/electron/main.js. Thermal printing goes through IPC (electron-pos-printer). Build with:

pnpm run electron-build

Auto-updates pull from https://download.dg-smartpos.co.ke.