Struktur Kodebase — Temuya Docs

Gambaran Umum

Pemahaman yang kuat mengenai tata letak direktori adalah kunci untuk menjadi kontributor yang efektif dalam proyek Temuya POS. Struktur kodebase kami telah diatur secara seksama untuk memisahkan domain tanggung jawab, sambil tetap mempertahankan kemudahan berbagi sumber daya di bawah payung satu repositori (monorepo-style dalam satu proyek).

Direktori src/ merupakan jantung dari seluruh aplikasi, yang dibagi menjadi beberapa domain utama: backend worker, frontend aplikasi react, kode yang dibagikan, serta modul-modul data. Penataan ini membantu menghindari kebingungan antara logika bisnis di sisi server dan logika presentasi di sisi klien, serta menjaga agar abstraksi tetap bersih dan terawat.

Alur Kerja

Saat Anda mengembangkan sebuah fitur baru, misalnya fitur ‘Diskon Pelanggan’, Anda akan berinteraksi dengan hampir seluruh bagian dari struktur folder ini. Anda akan mulai dengan mendefinisikan skema data di folder shared/, kemudian membuat endpoint API di worker/, dan akhirnya membangun antarmuka interaktif di react-app/.

graph TD
    subgraph Core["📁 Struktur Utama Project (src/)"]
        direction LR
        
        subgraph BE["⚙️ worker/ (Backend Edge)"]
            W1["index.ts (Hono Worker Entry)"]
        end

        subgraph FE["🎨 react-app/ (Frontend UI)"]
            R1["App.tsx (React Router v7)"]
            R2["pages/ (53 Halaman)"]
            R3["components/ (Komponen UI)"]
        end

        subgraph SH["🔗 shared/ (Tipe Data & Skema)"]
            S1["types.ts (Interface Shared)"]
            S2["navItems.ts (Menu Toko)"]
        end

        subgraph DB["📊 data/ & Config Rules"]
            D1["planFeatures.ts (Feature Gating)"]
            D2["rolePermissions.ts (RBAC Rules)"]
        end
    end

Visualisasi di atas memperlihatkan bagaimana kode dasar dipetakan ke dalam direktori-direktori logis. File index.ts pada worker merupakan titik masuk untuk backend, sedangkan App.tsx adalah tulang punggung dari routing frontend.

Teknologi & Infrastruktur

Beberapa file kritis dalam struktur ini menampung konfigurasi tingkat tinggi yang mengendalikan perilaku inti aplikasi.

Nama File / Folder	Peran dan Deskripsi
`worker/index.ts`	Entry point utama untuk Hono router. Di sini semua rute (routes) diregistrasi, middleware global diterapkan, dan worker diekspor agar dapat dijalankan oleh Cloudflare.
`react-app/App.tsx`	Entry point antarmuka pengguna. Menangani inisialisasi provider (seperti theme, auth context), dan mendefinisikan seluruh konfigurasi React Router v7.
`shared/`	Folder sakral tempat berkumpulnya skema Zod dan antarmuka TypeScript. Kode di sini diimpor oleh baik frontend maupun backend.
`data/planFeatures.ts`	Berisi daftar fitur yang tersedia untuk setiap paket langganan SaaS (Free, Pro, Enterprise). Digunakan untuk pembatasan fitur (feature gating).
`data/rolePermissions.ts`	Konfigurasi Role-Based Access Control (RBAC). Menentukan apakah seorang kasir, manajer, atau admin berhak melakukan tindakan tertentu.

Keterkaitan dengan Fitur Lain

Struktur folder ini sangat mendasari implementasi sistem multi-tenant. Sebagai contoh, logika middleware untuk mengidentifikasi tenant berada di worker/middlewares/tenantContext.ts, yang kemudian melindungi rute-rute di worker/routes/. Sementara itu, di react-app/, state tentang tenant yang sedang aktif dikelola dalam satu context global yang diakses oleh seluruh komponen UI.

Hal Penting yang Perlu Diketahui

Aturan emas (golden rule) dalam arsitektur folder ini adalah: Folder shared/ sama sekali tidak boleh mengimpor kode dari worker/ ataupun react-app/. Folder shared/ harus tetap murni dan tidak bergantung pada implementasi spesifik platform. Demikian pula, Anda dilarang mengimpor library spesifik browser ke dalam file yang akan dieksekusi di backend worker, karena hal itu akan memecah build process saat deploying ke Cloudflare.

Skenario Bisnis Lanjutan dan Kasus Penggunaan

Dalam skenario operasional ke-1, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-1 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-2, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-2 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-3, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-3 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-4, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-4 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-5, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-5 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-6, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-6 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-7, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-7 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-8, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-8 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-9, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-9 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-10, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-10 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-11, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-11 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-12, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-12 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-13, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-13 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-14, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-14 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.

Dalam skenario operasional ke-15, sistem dirancang untuk menangani berbagai macam kendala yang mungkin terjadi di lapangan. Misalnya, ketika seorang kasir menghadapi antrean yang sangat panjang di jam sibuk, setiap detik sangatlah berharga. Sistem Temuya POS memastikan bahwa waktu respons aplikasi tetap berada di bawah standar industri, memberikan pengalaman yang mulus dan meminimalisir kesalahan input data.

Bagi pemilik bisnis, informasi dari transaksi ke-15 ini akan langsung dikumpulkan dan diakumulasi pada dashboard laporan akhir hari. Keputusan strategis seperti penambahan stok barang, rotasi karyawan, hingga merencanakan promosi baru sangat bergantung pada kelengkapan dan kecepatan data yang disajikan oleh arsitektur sistem ini.