Skip to Content
Home

Retail System

Retail System is a multi-tenant SaaS platform for small to mid-sized retail businesses, such as convenience stores, minimarkets, supermarkets, department stores, wholesale stores, modern grocery stores, household supply stores, and other retail businesses. The platform helps retail business owners manage their business in an integrated way without having to build or maintain their own system.

One system covers all of a tenant’s operational needs: a backoffice and ERP to manage purchasing, stock, sales, and finance; a cashier app to serve in-store transactions; and an online store so customers can shop from their nearest store. All applications are connected to the same data, so stock, prices, and transactions stay in sync across every sales channel and every branch.

The project does not have an official name yet; the name Retail System is used for now.

Status: Research & Development. Retail System is not running in production yet. Business flows may still change because they are not yet bound to production data or users.

About These Docs

These docs are the source of truth for Retail System’s business flows. They contain product specifications, covering the business flow, rules, data structure, and access rights of each feature, not code documentation. Each feature is described in one PRD with a uniform eleven-section skeleton, from Overview to Dependencies, so readers always know which section holds the answer to a question. These docs serve four main purposes:

  • A shared reference for Frontend and Backend. The Business Rules in each PRD act as a contract: the backend enforces them, while the frontend uses them as form validation.
  • A testing reference. Since there is no separate QA, the acceptance criteria (AC) in each PRD become the checklist to ensure a feature works according to spec before it is considered done.
  • A record of product decisions. The outcomes of product discussions are written into the PRD so they do not get lost in conversations. Anything not yet decided is marked Needs confirmation, not guessed.
  • A knowledge base for AI agents. The structure is uniform and predictable, so agents can read and update PRDs with the same context as humans.

A guide to writing PRDs, along with a ready-to-copy skeleton, is available in the PRD Guideline.

Product Principles

Retail System is built for everyday use by retail business owners whose needs keep evolving. Because the team is small and the project is still in the R&D stage, the direction of development needs to be kept in check so that every feature stays easy to use, easy to extend, and consistent with one another. Every product and technical decision in Retail System follows these principles:

  • User-friendly. Users in a retail environment, such as cashiers, warehouse staff, and business owners, must be able to use the system without lengthy training. Ease of use and user experience are the main considerations for every feature.
  • Scalable & flexible. Features are designed to grow and adapt to the diverse needs of retail businesses, from a single small store to a network of branches.
  • Best practice & consistency. The same patterns are applied throughout the system: PRD structure, naming, UI behavior, and the FE–BE contract. Differences only appear when the business concept is genuinely different.
  • PRD-first. Every decision is written in the PRD first and only then implemented. If the implementation differs from the PRD, the implementation is adjusted, unless the difference is a new product decision; in that case, the PRD is updated first.

Multi-tenant Architecture

All tenants use the same single frontend codebase and single backend service. Separation happens at the data level: each tenant has its own domain, database, and object storage. The landlord also has its own database and object storage, separate from tenant data. As a result, new features are immediately available to all tenants, while data between tenants stays isolated.

In the following diagram, blue marks the tenant side and yellow marks the landlord side:

Layer Structure

The documentation is organized into three nested layers, from the broadest scope to the most specific. Each layer has its own page in the sidebar, so readers can explore the system from the big picture down to the details of a single feature:

  1. Application: an app used directly by users. Each application maps one-to-one to a folder in retail-app/apps, namely Tenant Backoffice, Tenant POS, Tenant Ecommerce, Landlord Backoffice, and Landlord Site, plus Tech Docs for the shared technical foundation. An application page explains the app’s purpose, its user scope (Tenant, Landlord, or Shared), and the list of modules inside it.
  2. Module: a group of related business functions within one application, for example Settings, Purchasing, or Inventory. A module page explains the module’s scope and contains a table of all features inside it, complete with their code, type, and implementation status.
  3. Feature: a specific function within a module, for example Purchase Order in the Purchasing module. Each feature is documented in one PRD with a unique code (for example PUR-PO) and a type describing the nature of its data: Transaction, Master Data, Configuration, or System Record.

The folder structure follows these layers, and URLs follow the file path, prefixed by the language. For example, the English Purchase Order PRD is located at content/en/tenant-backoffice/purchasing/purchase-order.md and can be accessed at /en/tenant-backoffice/purchasing/purchase-order.

Tech Stack

Retail System is built from two separately developed codebases, frontend and backend, with data stored in a database and object storage. Technology choices prioritize mature ecosystems, good documentation, and strong support for AI agent–assisted development. The technologies in each part are as follows:

1. Frontend

CategoryTechnology
FrameworkNext.js 16 (App Router), React 19 with React Compiler, TypeScript
MonorepoTurborepo + pnpm workspace; shared packages @repo/components (UI), @repo/common (hooks, utils, locales, types), and @repo/configs
Styling & UITailwind CSS 4, shadcn/ui on top of Base UI, Lucide Icons
Data fetching & stateTanStack Query, Axios, nuqs (state in the URL)
TablesTanStack Table
Forms & validationReact Hook Form + Zod
Internationalizationnext-intl
RealtimeLaravel Echo (connected to Laravel Reverb)
Visualization & documentsRecharts (charts), MapLibre GL (maps), React PDF (PDF documents)
Code qualityBiome (lint & format), Husky + Commitlint (Conventional Commits)

2. Backend

CategoryTechnology
FrameworkLaravel 12, PHP 8.2+
Multi-tenancySpatie Laravel Multitenancy (landlord database and per-tenant databases)
AuthenticationLaravel Sanctum
AuthorizationSpatie Laravel Permission (roles & permissions)
Audit trailSpatie Laravel Activitylog
Realtime & notificationsLaravel Reverb (WebSocket), Web Push
Queue, cache & sessionDatabase driver
Testing & code stylePest, Laravel Pint
ToolingLaravel Boost (context for AI agents), Laravel Sail, Laravel Pail

3. Data & Storage

CategoryTechnology
DatabasePostgreSQL: one landlord database and one database for each tenant
Object storageS3-compatible storage, separate for the landlord and each tenant

Team & Way of Working

Retail System is developed by two Product Engineers:

NameRoleFocus
Gayuh RidhoProduct EngineerFrontend, design, and product
Azis AlvriyantoProduct EngineerBackend, database, server, and infrastructure

The team has no PM, QA, or other separate roles. All work, from product discussions, PRD writing, design, and implementation to testing, is handled together.

The development process is supported by agentic AI, currently Claude Code, to write code, trace flows, and draft PRDs. That is why these docs are written with a consistent structure so they read well for both humans and agents. Writing rules for agents are listed in AGENTS.md in the docs repo.