# Arsitektur Sistem KeluargaMart Monorepo

## 1. Visi Arsitektur

KeluargaMart adalah platform enterprise retail omnichannel terpadu yang melayani berbagai channel bisnis:
- **ERP (Enterprise Resource Planning)**: Manajemen master data (produk, kategori, satuan), inventory/pergudangan, multi-outlet, purchasing/procurement, HR & payroll, keuangan & akuntansi, audit logs.
- **POS (Point of Sale)**: Aplikasi kasir kasir retail modern dengan dukungan barcode scanner cepat, penanganan transaksi offline-first, per-register shifts, receipt printing, dan sinkronisasi realtime.
- **B2B E-Commerce**: Toko online grosir untuk pembelian tier-based, manajemen pesanan skala besar, invoice terms, dan customer tiers.
- **Automated Reporting (NextReport)**: Engine penghasil laporan berkala, export PDF/Excel, dan analitik agregat.

Sebelum migrasi, sistem ini tersebar di 5 repositori terpisah (`keluargamart-backend`, `keluargamart-erp-frontend`, `keluargamart-pos-frontend`, `keluargamart-b2b-frontend`, dan submodule/repo `nextreport`). Monorepo menyatukan seluruh komponen ini ke dalam satu ekosistem yang terkelola dengan kontrak data yang kuat tanpa merusak batasan runtime.

```mermaid
graph TD
    subgraph Clients["Client Tier (Frontends & Tools)"]
        ERP["ERP Admin Portal<br/>(Vue 3 + Vite)"]
        POS["POS Cashier<br/>(Vue 3 + Vite)"]
        B2B["B2B Storefront<br/>(Nuxt 4)"]
        Report["NextReport Worker<br/>(Python)"]
    end

    subgraph Packages["Shared Workspace Packages"]
        Contracts["@keluargamart/contracts<br/>(Routes & Schemas)"]
        Perms["@keluargamart/permissions<br/>(198 RBAC Permissions)"]
        Utils["@keluargamart/utils<br/>(Formatters & Helpers)"]
        Client["@keluargamart/api-client<br/>(Axios Base Wrapper)"]
    end

    subgraph Core["Backend Core (Source of Truth)"]
        Backend["Go Chi REST API<br/>(Modular Monolith)"]
        DB[(PostgreSQL)]
        Cache[(Redis)]
        Storage[(MinIO / S3)]
    end

    ERP --> Contracts
    ERP --> Perms
    ERP --> Utils
    ERP --> Client

    POS --> Contracts
    POS --> Perms
    POS --> Utils
    POS --> Client

    B2B --> Contracts
    B2B --> Perms
    B2B --> Utils
    B2B --> Client

    ERP -.->|HTTP REST /api/v1| Backend
    POS -.->|HTTP REST /api/v1| Backend
    B2B -.->|HTTP REST /api/v1| Backend
    Report -.->|HTTP REST / Internal Token| Backend

    Backend --> DB
    Backend --> Cache
    Backend --> Storage
```

---

## 2. Prinsip "Single Source of Truth"

Backend Go (`apps/backend`) memegang tanggung jawab mutlak sebagai **Single Source of Truth**:
1. **Aturan Bisnis (Business Rules)**: Semua kalkulasi harga, diskon, pajak, perhitungan stok inventaris, payroll, dan workflow approval divalidasi dan dieksekusi di backend.
2. **Skema Database & Migrasi**: Seluruh migrasi database (menggunakan Go migrations) dikelola di `apps/backend/internal/database/migrations`.
3. **Otorisasi & Otoritas RBAC**: Definisi permission dan role tersentralisasi di `apps/backend/internal/modules/rbac/catalog.go`.
4. **Validasi Request**: Request validation di backend menggunakan schema Go structs dan binding middleware.
5. **Kontrak API**: Definisi endpoint terpusat di `apps/backend/docs/openapi.yaml`.

Frontend bertugas sebagai consumer antarmuka pengguna dan tidak boleh menggantikan atau menduplikasi logika otoritatif backend.

---

## 3. Komponen Monorepo

### `apps/backend` (Go 1.23+)
- Arsitektur: **Modular Monolith** dengan Go Chi router.
- Modules: Auth, Users, RBAC, Master Data, Products, Inventory, Orders, POS Sessions, Purchasing, Suppliers, HR/Payroll, Accounting, Auditing.
- Entrypoint: `cmd/server/main.go`.
- Output build: binary executable standalone `bin/server`.

### `apps/erp` (Vue 3 + Vite)
- Arsitektur: Single Page Application (SPA).
- UI Framework: Tailwind CSS, Headless UI, Heroicons, Lucide.
- State Management: Pinia.
- Target: Back-office management untuk pemilik bisnis, admin gudang, akuntan, dan tim HR.

### `apps/pos` (Vue 3 + Vite)
- Arsitektur: High-performance SPA dioptimalkan untuk register kasir.
- Features: Barcode scanning (`zxing-wasm`), split payments, receipt printing, keyboard shortcuts, offline queue.
- State Management: Pinia dengan persistence ke IndexedDB / LocalStorage.

### `apps/b2b` (Nuxt 4 + Vue 3)
- Arsitektur: SSR / Universal Nuxt application.
- Features: Wholesale catalog, price tiering, cart session handling, order placement, customer account management.
- State Management: Pinia + Nuxt useState.

### `apps/nextreport` (Python 3.10+)
- Arsitektur: Report generation service / worker.
- Output: PDF & XLSX export untuk laporan keuangan, inventory valuation, dan sales summary.

---

## 4. Keuntungan Monorepo untuk KeluargaMart

1. **Atomic Commits Lintas Service**: Perubahan skema API dapat dilakukan bersamaan dengan penyesuaian frontend dalam satu commit yang koheren.
2. **Eliminasi Copy-Paste Routes & Permissions**: Menghilangkan file teks duplikasi di masing-masing frontend yang rawan drift.
3. **Penyelarasan Tooling**: Satu eksekusi `pnpm test` menjalankan 625+ test di seluruh ekosistem dalam hitungan detik.
4. **Percepatan Onboarding**: Developer baru hanya perlu meng-clone 1 repositori dan menjalankan satu command `pnpm install` untuk memulai.