Retail System
Retail System adalah platform SaaS multi-tenant untuk bisnis retail skala kecil hingga menengah, seperti swalayan, minimarket, supermarket, toserba, toko grosir, toko kelontong modern, toko perlengkapan rumah tangga, dan bisnis retail lainnya. Platform ini membantu pelaku usaha retail mengelola bisnisnya secara terintegrasi tanpa harus membangun atau merawat sistem sendiri.
Satu sistem mencakup seluruh kebutuhan operasional tenant: backoffice dan ERP untuk mengelola pembelian, stok, penjualan, dan keuangan; aplikasi kasir untuk melayani transaksi di toko; hingga toko online agar pelanggan dapat berbelanja dari toko terdekat. Seluruh aplikasi terhubung ke data yang sama, sehingga stok, harga, dan transaksi tetap sinkron di setiap kanal penjualan dan setiap cabang.
Project ini belum memiliki nama resmi; untuk sementara digunakan nama Retail System.
Status: Research & Development. Retail System belum berjalan di production. Flow bisnis masih dapat berubah karena belum terikat pada data maupun pengguna production.
Tentang Docs
Docs ini adalah source of truth untuk flow bisnis Retail System. Isinya berupa spesifikasi produk, meliputi alur bisnis, aturan, struktur data, dan hak akses setiap fitur, bukan dokumentasi kode. Setiap fitur dijelaskan dalam satu PRD dengan kerangka sebelas section yang seragam, mulai dari Overview hingga Dependencies, sehingga pembaca selalu tahu di bagian mana jawaban sebuah pertanyaan berada. Docs ini memiliki empat fungsi utama:
- Rujukan bersama Frontend dan Backend. Business Rules pada setiap PRD berfungsi sebagai kontrak: backend menegakkannya, sedangkan frontend menggunakannya sebagai validasi form.
- Acuan pengujian. Karena tidak ada QA terpisah, kriteria penerimaan (AC) pada setiap PRD menjadi checklist untuk memastikan fitur berjalan sesuai spesifikasi sebelum dianggap selesai.
- Catatan keputusan produk. Hasil diskusi produk dituangkan ke PRD agar tidak tercecer di percakapan. Hal yang belum diputuskan ditandai Perlu dikonfirmasi, bukan ditebak.
- Base knowledge untuk AI agent. Strukturnya seragam dan mudah ditebak sehingga agent dapat membaca serta memperbarui PRD dengan konteks yang sama seperti manusia.
Panduan menulis PRD beserta kerangka siap salin tersedia di Panduan PRD.
Prinsip Produk
Retail System dibangun untuk dipakai sehari-hari oleh pelaku usaha retail dengan kebutuhan yang terus berkembang. Karena tim kecil dan project masih dalam tahap RnD, arah pengembangan perlu dijaga agar setiap fitur tetap mudah digunakan, mudah dikembangkan, dan konsisten satu sama lain. Setiap keputusan produk dan teknis di Retail System berpegang pada prinsip berikut:
- User-friendly. Pengguna di lingkungan retail, seperti kasir, staf gudang, dan pemilik usaha, harus dapat menggunakan sistem tanpa pelatihan yang panjang. Kemudahan dan pengalaman pengguna menjadi pertimbangan utama di setiap fitur.
- Scalable & flexible. Fitur dirancang agar dapat berkembang dan menyesuaikan diri dengan kebutuhan bisnis retail yang beragam, dari satu toko kecil hingga jaringan cabang.
- Best practice & consistency. Pola yang sama diterapkan di seluruh sistem: struktur PRD, penamaan, perilaku UI, dan kontrak FE–BE. Perbedaan hanya muncul bila konsep bisnisnya memang berbeda.
- PRD-first. Setiap keputusan ditulis di PRD lebih dulu, baru kemudian diimplementasikan. Bila implementasi berbeda dari PRD, implementasi yang disesuaikan, kecuali perbedaan tersebut merupakan keputusan produk baru; dalam hal itu, PRD diperbarui lebih dulu.
Arsitektur Multi-tenant
Seluruh tenant menggunakan satu codebase frontend dan satu service backend yang sama. Pemisahan dilakukan pada level data: setiap tenant memiliki domain, database, dan object storage sendiri. Landlord juga memiliki database dan object storage tersendiri yang terpisah dari data tenant. Dengan demikian, fitur baru langsung tersedia bagi semua tenant, sementara data antar-tenant tetap terisolasi.
Pada diagram berikut, warna biru menandai sisi tenant dan warna kuning menandai sisi landlord:
Struktur Layer
Dokumentasi disusun dalam tiga layer bertingkat, dari cakupan paling luas hingga paling spesifik. Setiap layer memiliki halaman sendiri di sidebar, sehingga pembaca dapat menelusuri sistem dari gambaran besar hingga detail satu fitur:
- Application: aplikasi yang digunakan langsung oleh pengguna. Setiap application dipetakan satu banding satu ke folder di
retail-app/apps, yaitu Tenant Backoffice, Tenant POS, Tenant Ecommerce, Landlord Backoffice, dan Landlord Site, serta Tech Docs untuk fondasi teknis yang dipakai bersama. Halaman application menjelaskan tujuan aplikasi, scope penggunanya (Tenant, Landlord, atau Shared), dan daftar module di dalamnya. - Module: kelompok fungsi bisnis yang saling berkaitan di dalam satu application, misalnya Settings, Purchasing, atau Inventory. Halaman module menjelaskan cakupan module tersebut dan memuat tabel seluruh feature di dalamnya, lengkap dengan kode, tipe, dan status implementasinya.
- Feature: fungsi spesifik di dalam module, misalnya Purchase Order di module Purchasing. Setiap feature didokumentasikan dalam satu PRD dengan kode unik (misalnya
PUR-PO) dan tipe yang menggambarkan sifat datanya: Transaction, Master Data, Configuration, atau System Record.
Struktur folder mengikuti layer tersebut, dan URL mengikuti path file. Sebagai contoh, PRD Purchase Order berada di content/tenant-backoffice/purchasing/purchase-order.md dan dapat diakses di /tenant-backoffice/purchasing/purchase-order.
Tech Stack
Retail System dibangun dari dua codebase yang dikembangkan terpisah, yaitu frontend dan backend, dengan data yang tersimpan di database dan object storage. Pemilihan teknologi mengutamakan ekosistem yang matang, dokumentasi yang baik, dan dukungan yang kuat untuk pengembangan berbantuan AI agent. Rincian teknologi di setiap bagian adalah sebagai berikut:
1. Frontend
| Kategori | Teknologi |
|---|---|
| Framework | Next.js 16 (App Router), React 19 dengan React Compiler, TypeScript |
| Monorepo | Turborepo + pnpm workspace; package bersama @repo/components (UI), @repo/common (hooks, utils, locales, types), dan @repo/configs |
| Styling & UI | Tailwind CSS 4, shadcn/ui di atas Base UI, Lucide Icons |
| Data fetching & state | TanStack Query, Axios, nuqs (state di URL) |
| Tabel | TanStack Table |
| Form & validasi | React Hook Form + Zod |
| Internasionalisasi | next-intl |
| Realtime | Laravel Echo (terhubung ke Laravel Reverb) |
| Visualisasi & dokumen | Recharts (grafik), MapLibre GL (peta), React PDF (dokumen PDF) |
| Code quality | Biome (lint & format), Husky + Commitlint (Conventional Commits) |
2. Backend
| Kategori | Teknologi |
|---|---|
| Framework | Laravel 12, PHP 8.2+ |
| Multi-tenancy | Spatie Laravel Multitenancy (database landlord dan database per tenant) |
| Autentikasi | Laravel Sanctum |
| Otorisasi | Spatie Laravel Permission (role & permission) |
| Audit trail | Spatie Laravel Activitylog |
| Realtime & notifikasi | Laravel Reverb (WebSocket), Web Push |
| Queue, cache & session | Database driver |
| Testing & code style | Pest, Laravel Pint |
| Tooling | Laravel Boost (konteks untuk AI agent), Laravel Sail, Laravel Pail |
3. Data & Storage
| Kategori | Teknologi |
|---|---|
| Database | PostgreSQL: satu database landlord dan satu database untuk setiap tenant |
| Object storage | S3-compatible storage, terpisah untuk landlord dan setiap tenant |
Tim & Cara Kerja
Retail System dikembangkan oleh dua orang Product Engineer:
| Nama | Peran | Fokus |
|---|---|---|
| Gayuh Ridho | Product Engineer | Frontend, design, dan produk |
| Azis Alvriyanto | Product Engineer | Backend, database, server, dan infrastruktur |
Tim tidak memiliki PM, QA, maupun peran terpisah lainnya. Seluruh pekerjaan, mulai dari diskusi produk, penulisan PRD, desain, implementasi, hingga pengujian, ditangani bersama.
Proses pengembangan didukung oleh agentic AI, saat ini Claude Code, untuk menulis kode, menelusuri flow, dan menyusun PRD. Oleh karena itu, docs ini ditulis dengan struktur yang konsisten agar dapat dibaca dengan baik oleh manusia maupun agent. Aturan penulisan bagi agent tercantum di AGENTS.md pada repo docs.