CemilanKasirPOS Nusantara

CemilanKasirPOS adalah aplikasi kasir dengan fitur yang cukup lengkap dan mudah digunakan.

🍬 Aplikasi Kasir - CemilanKasirPOS React-PHP

• Frontend Framework: React 19
• Build Tool: Vite
• Language: TypeScript
• Styling: Tailwind CSS
• Icons: Lucide React
• Charts: Recharts
• Backend: PHP Native
• Database: MySQL

Dibuat dengan bantuan Google AI Studio App, Google Antigravity, Agent model: Gemini 3 Pro dan Claude Sonnet 4.5

Fitur AI di aplikasi ini yang menggunakan Gemini API, kami belum sempat mencobanya.

Untuk versi Cemilan KasirPOS dengan pendekatan database yang berbeda, seperti localStorage, IndexedDB-Dexie, hybrid database (IndexedDB-Dexie + MySQL), dapat dicek di laman rilis repo Cemilan KasirPOS Nusantara - Testing https://github.com/dotslashgabut/CemilanKasirPOS-Aplikasi-Kasir-React-NodeJS/releases

Video tutorialnya cek aja nanti di DotSlashGabut YouTube, belum sempet bikin

🍵 Traktir Kami Cendol

via Saweria https://saweria.co/dotslashgabut

via Trakteer https://trakteer.id/dotslashgabut

via Ko-fi https://ko-fi.com/dotslashgabut

Semoga sistem POS (Point of Sale) - Aplikasi Kasir ini bermanfaat bagi semuanya, terutama warung kecil dan UMKM. Terima Kasih.

📃 Panduan singkat instalasi dan penggunaan aplikasi Cemilan KasirPOS

Aplikasi ini dirilis dalam dua file arsip berbeda. Untuk file arsip dengan nama 'full', itu sudah termasuk node module yang diperlukan, siap pakai. Sedangkan untuk file arsip tanpa nama 'full', belum termasuk node modul, file-filenya sama seperti yang ada di repository, diperlukan penginstalan modul-modulnya.

Panduan instalasi dan penggunaan untuk Development, selengkapnya bisa dibaca di README_DEVELOPMENT.md, dan untuk Production bisa dibaca di README_PRODUCTION.md

🍬 Cemilan KasirPOS Nusantara

Cemilan KasirPOS is a modern, feature-rich Point of Sale (POS) application designed for small to medium-sized businesses in Indonesia. Built with React, TypeScript, and Vite, it offers a fast and responsive interface for managing sales, inventory, customers, and finances.

🇮🇩 Baca versi Bahasa Indonesia di bawah

🚀 Features

Point of Sale (POS)

• Efficient Checkout: Fast product selection with search and barcode support.
• Flexible Pricing: Support for multiple price tiers (Eceran, Umum, Grosir, Promo) per product.
• Payment Methods: Accept Cash, Bank Transfer, and Tempo (Credit).
• Partial Payments: Support for down payments and installments for credit transactions.
• Cart Management: Easy addition, modification, and removal of items.

Product Management

• Inventory Tracking: Real-time stock monitoring with low stock alerts.
• Product Organization: Categorize products for easy management.
• Barcode Generator: Built-in tool to generate and print barcodes for products.
• Cost Tracking: Track HPP (Harga Pokok Penjualan) to calculate profits accurately.

Finance & Accounting

• Transaction History: Detailed log of all sales and purchases.
• Accounts Receivable (Piutang): Track and manage customer debts with installment history.
• Accounts Payable (Utang): Manage supplier debts and purchase history.
• Cash Flow: Monitor incoming and outgoing operational expenses.
• Profit & Loss: View estimated profit and loss reports.
• Sold Items Report: Dedicated report for tracking sold items with export and print capabilities.
• Returns Management: Process sales returns and purchase returns with automatic stock adjustment.
• Bulk Delete & Data Pruning: Superadmin features to delete multiple transactions at once and prune old financial data automatically.

User & People Management

• Role-Based Access Control:
  • Superadmin: Full access to all system features.
  • Owner: Administrative access but restricted from critical system settings.
  • Cashier: Restricted access focused on sales and basic operations.
• Customer Database: Manage customer profiles and assign default price tiers.
• Supplier Management: Keep track of supplier details for purchasing.

Settings & Customization

• Store Profile: Customize store name, address, contact info, and receipt footer.
• Print Layouts: Support for various receipt formats (58mm, 80mm, A4) for invoices and delivery notes.
• Bank Accounts: Manage bank accounts for transfer payments.
• Themes & Appearance:
  • Dynamic Theming: Customize the primary app color (Hue & Saturation) to match your brand.
  • Login Customization: Choose from preset gradients, upload your own background image, or match the login screen to your theme.
  • Branding: "Cemilan" inspired default theme (Red Spicy) and custom Candy favicon.

🛠️ Tech Stack

• Frontend Framework: React 19
• Build Tool: Vite
• Language: TypeScript
• Styling: Tailwind CSS
• Icons: Lucide React
• Charts: Recharts
• Backend: PHP Native
• Database: MySQL

💾 Data Persistence

This application uses MySQL as the primary database for robust data storage, scalability, and multi-device access.

Architecture

┌─────────────────────────────────────────────────┐
│           React Components (UI Layer)           │
│  - Dashboard, POS, Finance, Products, etc.      │
└──────────────────┬──────────────────────────────┘
                   │ useData (Reactive Hook)
                   │
┌──────────────────▼──────────────────────────────┐
│         StorageService (Business Logic)         │
│  - Abstraction Layer                            │
│  - Handles data fetching and updates            │
└──────────────────┬──────────────────────────────┘
                   │ HTTP API Calls
                   │
┌──────────────────▼──────────────────────────────┐
│            ApiService (API Layer)               │
│  - Communicates with Backend                    │
└──────────────────┬──────────────────────────────┘
                   │ REST API
                   │
┌──────────────────▼──────────────────────────────┐
│           Backend Server (PHP)                  │
│  - API Endpoints (php_server/)                  │
│  - PHP Native                                   │
└──────────────────┬──────────────────────────────┘
                   │ SQL
                   │
┌──────────────────▼──────────────────────────────┐
│             MySQL Database                      │
│  - Persistent Storage                           │
└─────────────────────────────────────────────────┘

Database Schema

The application uses the following tables:

Table	Primary Key	Indexes	Description
products	id	name, sku, categoryId	Product catalog and inventory
categories	id	name	Product categories
customers	id	name, phone	Customer database
suppliers	id	name	Supplier contacts
transactions	id	date, customerId	Sales transactions
purchases	id	date, supplierId	Purchase orders
cashflow	id	date, type	Cash flow entries
users	id	username	User accounts
banks	id	-	Bank accounts for transfers
store_settings	id	-	Application settings

📦 Installation & Development Setup

Follow these steps to set up the project for development.

Prerequisites

• Node.js: Version 18 or higher.

• MySQL: Ensure MySQL server is installed and running.

  1. Database Setup

1. Create a new MySQL database (e.g., cemilankasirpos_php_v02).

2. Import the schema from cemilankasirpos_php_v02.sql (optional, as Sequelize will sync tables, but good for initial structure).

   2. Backend Setup (PHP)

3. Configure Database & Environment:

   • Navigate to php_server/.
   • Copy .env.example to .env:

     cp .env.example .env

   • Open .env and update the database credentials and JWT secret.

4. Start PHP Server:

   • If you have PHP installed locally:

     cd php_server
     php -S localhost:8000

   • Or use XAMPP/Laragon and point the document root to php_server.

3. Frontend Setup (React)

7. Open a new terminal and navigate to the project root.

8. Install dependencies:

   npm install

9. Start the Frontend Application:

   npm run dev

10. Open your browser and visit http://localhost:5173 (or the URL shown in the terminal).

See README_DEVELOPMENT.md for detailed setup instructions.

🏗️ Project Structure

/
├── components/   # Reusable UI components
├── pages/        # Main application pages (POS, Dashboard, Finance, etc.)
├── services/     # API and storage services
├── hooks/        # Custom React hooks (useData, etc.)
├── utils/        # Utility functions and helpers
├── types.ts      # TypeScript type definitions
├── App.tsx       # Main application component
├── index.tsx     # Entry point
├── vite.config.ts
└── cemilankasirpos_php_v02.sql # Database schema

👥 User Roles

• SUPERADMIN: Has absolute control over the system, including managing other admins.
• OWNER: Can manage products, view reports, and change store settings.
• CASHIER: Can perform sales transactions and view products but cannot modify stock or view sensitive financial data (like HPP).

🔒 Security Features (Diperbarui 2026)

• Advanced Authentication: Dual-mode auth support with HttpOnly Cookies (Browser) and Bearer Tokens (API).
• HSTS Enforcement: Automatic HTTP Strict Transport Security when HTTPS is detected to prevent downgrade attacks.
• Strict CORS: Dynamic origin validation with credential support for secure cross-origin requests.
• Rate Limiting: File-locking mechanism to prevent race conditions during brute-force attacks.
• Data Isolation: Strictly enforced at the backend level ensuring Cashiers only see their own transactions.

For a detailed security audit report, see SECURITY_AUDIT.md.

Default Login Credentials

Note: Upon first login, the system will automatically encrypt the default password.

• Username: superadmin
• Password: password

🚀 Deployment Guides

This application can be deployed in various ways:

📖 Available Guides:

1. Development Guide - Panduan untuk setup lingkungan pengembangan (development environment) untuk aplikasi Cemilan KasirPOS menggunakan Backend PHP Native
2. Production Guide - Langkah-langkah persiapan sebelum build (build preparation) dan konfigurasi untuk deployment aplikasi ke server produksi (live server)
3. Panduan Hosting cPanel - Panduan deploy ke shared hosting menggunakan cPanel
4. Panduan Run Locally (Universal) - Panduan menjalankan aplikasi di lokal (XAMPP, Laragon, PHP Built-in)
5. Docker Deployment - Panduan menjalankan aplikasi menggunakan Docker dan Docker Compose

📝 License

This application was built with the assistance of several AI LLMs, primarily the Gemini 3 Pro and Claude 4.5 Sonnet model.

---

🇮🇩 Bahasa Indonesia

Cemilan KasirPOS adalah aplikasi Point of Sale (POS) modern yang kaya fitur, dirancang untuk usaha kecil hingga menengah di Indonesia. Dibangun dengan React, TypeScript, dan Vite, aplikasi ini menawarkan antarmuka yang cepat dan responsif untuk mengelola penjualan, inventaris, pelanggan, dan keuangan.

🚀 Fitur

Point of Sale (POS) / Kasir

• Checkout Efisien: Pemilihan produk cepat dengan pencarian dan dukungan barcode.
• Harga Fleksibel: Mendukung berbagai tingkatan harga (Eceran, Umum, Grosir, Promo) per produk.
• Metode Pembayaran: Menerima Tunai, Transfer Bank, dan Tempo (Kredit).
• Pembayaran Parsial: Dukungan untuk uang muka (DP) dan cicilan untuk transaksi kredit.
• Manajemen Keranjang: Penambahan, pengubahan, dan penghapusan item dengan mudah.

Manajemen Produk

• Pelacakan Inventaris: Pemantauan stok real-time dengan peringatan stok rendah.
• Organisasi Produk: Kategorisasi produk untuk pengelolaan yang mudah.
• Generator Barcode: Alat bawaan untuk membuat dan mencetak barcode produk.
• Pelacakan Biaya: Melacak HPP (Harga Pokok Penjualan) untuk menghitung keuntungan secara akurat.

Keuangan & Akuntansi

• Riwayat Transaksi: Log rinci semua penjualan dan pembelian.
• Piutang Pelanggan: Lacak dan kelola hutang pelanggan dengan riwayat cicilan.
• Utang Supplier: Kelola hutang ke pemasok dan riwayat pembelian.
• Arus Kas: Pantau pengeluaran operasional masuk dan keluar.
• Laba Rugi: Lihat laporan perkiraan laba dan rugi.
• Laporan Barang Terjual: Laporan khusus untuk melacak barang terjual dengan fitur ekspor dan cetak.
• Manajemen Retur: Proses retur penjualan dan retur pembelian dengan penyesuaian stok otomatis.
• Penghapusan Massal & Pembersihan Data: Fitur superadmin untuk menghapus banyak transaksi sekaligus atau membersihkan data lama secara otomatis (Data Pruning).

🔒 Fitur Keamanan (Diperbarui 2026)

• Autentikasi Canggih: Mendukung dual-mode dengan HttpOnly Cookies (Browser) dan Bearer Token (API) untuk keamanan maksimal.
• Penerapan HSTS: Otomatis mendeteksi HTTPS dan mengaktifkan proteksi Strict Transport Security.
• CORS Ketat: Validasi origin dinamis dengan dukungan kredensial untuk request lintas domain yang aman.
• Rate Limiting: Mekanisme penguncian file (file locking) di backend untuk mencegah race condition saat serangan brute-force.
• Isolasi Data: Pembatasan akses backend yang ketat, memastikan Kasir hanya bisa melihat transaksi mereka sendiri.

Untuk laporan audit keamanan lengkap, lihat SECURITY_AUDIT.md.

Manajemen Pengguna & Orang

• Database Pelanggan: Kelola profil pelanggan dan tetapkan tingkatan harga default.
• Manajemen Supplier: Simpan detail pemasok untuk pembelian.

Pengaturan & Kustomisasi

• Profil Toko: Sesuaikan nama toko, alamat, info kontak, dan footer struk.
• Layout Cetak: Dukungan untuk berbagai format struk (58mm, 80mm, A4) untuk faktur dan surat jalan.
• Akun Bank: Kelola akun bank untuk pembayaran transfer.
• Tema & Tampilan:
  • Tema Dinamis: Sesuaikan warna utama aplikasi (Hue & Saturation) agar cocok dengan brand Anda.
  • Kustomisasi Login: Pilih dari gradien preset, unggah gambar latar sendiri, atau sesuaikan layar login dengan tema Anda.
  • Branding: Tema bawaan terinspirasi "Cemilan" (Merah Pedas) dan ikon Permen kustom.

🛠️ Teknologi yang Digunakan

• Frontend: React (v18+) + Vite + TypeScript
  • State Management: React Hooks & Context
  • Styling: Tailwind CSS
  • Icons: Lucide React
• Backend: PHP Native (Tanpa Framework)
  • Lokasi: Folder php_server/
  • Database: MySQL
  • Auth: JWT (JSON Web Tokens) & HttpOnly Cookies
  • Security: RBAC, Rate Limiting, Input Validation, CSRF Protection via SameSite Cookies
• Deployment: Kompatibel penuh dengan cPanel / Shared Hosting (Apache/Nginx)

📂 Struktur Folder

cemilan-kasirpos/
├── src/                # Source code Frontend (React)
├── public/             # Aset statis (icon, logo)
├── php_server/         # Source code Backend (PHP API)
│   ├── .env            # Konfigurasi Environment (DB & Security)
│   ├── .htaccess       # Apache Routing & Security Rules
│   ├── index.php       # Main Router
│   ├── config.php      # Config Handler
│   ├── auth.php        # Middleware Auth (JWT)
│   ├── logic.php       # Business Logic
│   └── ...
├── dist/               # Hasil build Frontend (setelah npm run build)
├── screenshots/        # Aset gambar untuk dokumentasi
└── ... config files

💾 Penyimpanan Data

Aplikasi ini menggunakan MySQL sebagai database utama untuk penyimpanan data yang handal, skalabilitas, dan akses multi-perangkat.

Arsitektur

┌─────────────────────────────────────────────────┐
│           Komponen React (Lapisan UI)           │
│  - Dashboard, POS, Finance, Products, dll.      │
└──────────────────┬──────────────────────────────┘
                   │ useData (Hook Reaktif)
                   │
┌──────────────────▼──────────────────────────────┐
│      StorageService (Logika Bisnis)             │
│  - Lapisan Abstraksi                            │
│  - Menangani pengambilan dan pembaruan data     │
└──────────────────┬──────────────────────────────┘
                   │ Panggilan HTTP API
                   │
┌──────────────────▼──────────────────────────────┐
│            ApiService (Lapisan API)             │
│  - Berkomunikasi dengan Backend                 │
└──────────────────┬──────────────────────────────┘
                   │ REST API
                   │
┌──────────────────▼──────────────────────────────┐
│           Backend Server (PHP)                  │
│  - Endpoint API (php_server/)                   │
│  - PHP Native                                   │
└──────────────────┬──────────────────────────────┘
                   │ SQL
                   │
┌──────────────────▼──────────────────────────────┐
│             Database MySQL                      │
│  - Penyimpanan Persisten                        │
└─────────────────────────────────────────────────┘

📦 Instalasi

1. Clone repositori (jika ada) atau navigasikan ke direktori proyek.

2. Install Dependensi Frontend:

   npm install

▶️ Menjalankan Aplikasi

Untuk memulai lingkungan pengembangan:

1. Jalankan Server Backend:

   • Pastikan server MySQL Anda berjalan.

   • Masuk ke direktori server:

     cd php_server

   • Konfigurasi Environment: Salin .env.example ke .env dan sesuaikan setting database/security:

     cp .env.example .env

   • Jalankan server:

     php -S localhost:8000

   • Server akan berjalan di http://localhost:8000.

2. Jalankan Aplikasi Frontend (Di terminal baru):

   npm run dev

Aplikasi akan tersedia di http://localhost:5173.

🚀 Panduan Deployment

Aplikasi ini dapat di-deploy dengan berbagai cara:

📖 Panduan yang Tersedia:

1. Development Guide - Panduan untuk setup lingkungan pengembangan (development environment) untuk aplikasi Cemilan KasirPOS menggunakan Backend PHP Native
2. Production Guide - Langkah-langkah persiapan sebelum build (build preparation) dan konfigurasi untuk deployment aplikasi ke server produksi (live server)
3. Panduan Hosting cPanel - Deploy ke shared hosting dengan cPanel
4. Panduan Run Locally (Universal) - Panduan menjalankan aplikasi di lokal (XAMPP, Laragon, PHP Built-in)
5. Deployment Docker - Jalankan dengan Docker dan Docker Compose

📝 Lisensi

Aplikasi ini dibuat dengan bantuan beberapa AI LLM, terutama model Gemini 3 Pro dan Claude 4.5 Sonnet.