Operating problem

Independent local businesses often split customer journeys, orders, staffing, stock, and daily controls across disconnected tools. That fragmentation makes each handoff harder to operate and verify.

What changed

Kuan built Perko as one multi-tenant system connecting the customer marketplace, venue experience, staff workflows, owner controls, and production infrastructure.

System scope

• Customer marketplace, menus, and rewards
• Counter, kitchen, inventory, workforce, and owner controls
• Multi-tenant API, PostgreSQL records, authorization, and audit history
• Kazakhstan deployment, encrypted backups, recovery, and monitoring

Technical constraints

• Keep customer, staff, and owner views consistent while each tenant and location retains explicit authority over its records.
• Connect orders, stock, staffing, payments, and rewards without merging financial or operational truth across businesses.
• Deploy and migrate the system without weakening audit history or backup recovery.

Evidence

Pilot

Solid Coffee in Almaty tested and accepted the full counter-to-close workflow in September 2026.

Production

Runs on its own infrastructure in Kazakhstan, with encrypted backups, recovery, and monitoring.

Technical foundation

Applications

React and TypeScript across responsive web and PWA surfaces, with Capacitor shells for iOS and Android.

API and data

A Fastify API over PostgreSQL 17, with append-only events and ledgers preserving operational history.

Architecture

A first-party modular monolith: one tenancy, identity, authorization, audit, and module kernel serving customer, staff, owner, and operator channels.

Production runtime

Docker Compose behind Caddy, with isolated web, API, and PostgreSQL services, encrypted backups, restore checks, and one API writer.

Key decisions

Configure one platform instead of forking it per business

One release and schema serve multiple tenants and locations. Modules, business blueprints, and country packs change the operating composition without creating tenant-specific codebases.

Keep business truth on the server

PostgreSQL owns orders, stock, money, workforce, and permissions. Client state and provider systems remain projections or adapters; they cannot silently replace authoritative records.

Preserve provenance rather than overwrite history

Consequential mutations retain tenant, location, actor, device, timestamps, idempotency, and retry lineage. Corrections append compensating facts instead of editing protected history.

Separate identity, membership, and financial responsibility

Authentication identity, customer membership, and staff assignment remain distinct. Orders and reward liabilities keep their source business and location instead of being merged across the network.

Fail closed when operational truth is uncertain

Module access requires separate entitlement, activation, readiness, rollout, and permission checks. Unsupported offline payments and unresolved financial or sync states stay blocked and visible.