# KeluargaMart Monorepo

> **Unified Enterprise Retail, B2B E-Commerce, POS & Reporting Platform**

Monorepo terintegrasi untuk ekosistem **KeluargaMart**, menggabungkan Go modular monolith backend, Vue 3 ERP admin portal, Vue 3 POS (Point of Sale) SPA, Nuxt 4 B2B E-Commerce marketplace, serta Python automated reporting engine ke dalam satu arsitektur repositori terpadu yang dikelola dengan **pnpm workspaces** dan diorkestrasi menggunakan **Turborepo**.

---

## 📑 Daftar Isi

- [Struktur Repositori](#-struktur-repositori)
- [Aplikasi & Layanan](#-aplikasi--layanan)
- [Shared Packages](#-shared-packages)
- [Prasyarat Sistem](#-prasyarat-sistem)
- [Quick Start](#-quick-start)
- [Daftar Command Utama](#-daftar-command-utama)
- [API Contract & Permission Drift Guard](#-api-contract--permission-drift-guard)
- [Infrastruktur & Container](#-infrastruktur--container)
- [Dokumentasi Lengkap](#-dokumentasi-lengkap)
- [Troubleshooting](#-troubleshooting)

---

## 🏛️ Struktur Repositori

```text
keluargamart-monorepo/
├── apps/
│   ├── backend/             # Go 1.23+ Chi REST API (Source of Truth, Modular Monolith)
│   ├── erp/                 # Vue 3 + Vite + Tailwind CSS ERP Admin Portal
│   ├── pos/                 # Vue 3 + Vite Offline-First Cashier POS
│   ├── b2b/                 # Nuxt 4 + Tailwind CSS B2B E-Commerce Storefront
│   └── nextreport/          # Python Reporting Worker / Report Generator
│
├── packages/
│   ├── contracts/           # Canonical API routes & DTO schema derived from OpenAPI
│   ├── permissions/         # Canonical permission catalog & RBAC evaluation helper
│   ├── utils/               # Shared business formatting (Rupiah, Date, Idempotency)
│   └── api-client/          # Shared Axios HTTP client wrapper with error handling
│
├── infra/
│   ├── containers/          # Podman / Docker compose deployment configurations
│   └── reverse-proxy/       # Unified gateway & reverse proxy (Caddyfile)
│
├── scripts/
│   └── check-drift.py       # Automated drift guard (OpenAPI vs catalog.go vs packages)
│
├── docs/                    # Architectural specs, migration logs, runbooks, and ADRs
│   ├── architecture/        # Architecture overview, boundaries, dependency graphs
│   ├── migration/           # Polyrepo to monorepo transition record and baselines
│   ├── development/         # Developer guides, API workflow, environment matrix
│   ├── deployment/          # Containerization, reverse proxy, CI/CD runbook
│   └── adr/                 # Architecture Decision Records (ADRs)
│
├── .github/workflows/       # Monorepo CI/CD pipelines (Test, Lint, Build, GHCR Publish)
├── package.json             # Root workspace manifests & global scripts
├── pnpm-workspace.yaml      # pnpm workspace definition
├── turbo.json               # Turborepo task pipeline orchestration & cache configuration
└── README.md
```

---

## 🚀 Aplikasi & Layanan

| Aplikasi | Path | Port Lokal | Deskripsi & Tech Stack |
|---|---|---|---|
| **Backend** | `apps/backend` | `:8080` | Go 1.23+, Chi router, PostgreSQL, Redis, Modular Monolith. Source of truth untuk business logic & database. |
| **ERP Portal** | `apps/erp` | `:5173` | Vue 3, Vite, Tailwind CSS, Pinia, Vue Router. Back-office ERP management. |
| **POS Frontend** | `apps/pos` | `:5174` | Vue 3, Vite, Tailwind CSS. Kasir POS kasir dengan dukungan offline scanning. |
| **B2B E-Commerce** | `apps/b2b` | `:3000` | Nuxt 4, Vue 3, Tailwind CSS. Wholesale B2B storefront. |
| **NextReport** | `apps/nextreport` | `:8000` | Python Report Engine & automated batch export generator. |
| **Reverse Proxy** | `infra/reverse-proxy` | `:80 / :443` | Caddy reverse proxy / gateway untuk routing terpadu domain & sub-path. |

---

## 📦 Shared Packages

Semua package internal berada di namespace `@keluargamart/*` dan di-link otomatis melalui `workspace:*`:

1. **`@keluargamart/contracts`** (`packages/contracts`):
   - Daftar 368 endpoint canonical backend API (`src/routes.js`, `src/routes.d.ts`, `src/routes.txt`).
   - Mencegah typo path URL dan menjamin sinkronisasi endpoint antara backend dan semua frontend.
2. **`@keluargamart/permissions`** (`packages/permissions`):
   - Daftar 198 permission RBAC canonical (`src/index.js`, `src/index.d.ts`, `src/permissions.txt`).
   - Menyediakan fungsi helper `can(userPermissions, requiredPermission, userRole)`.
3. **`@keluargamart/utils`** (`packages/utils`):
   - Utilitas formatting bisnis terstandarisasi: `formatRupiah`, `formatIDR`, `formatNumber`, `parseMoney`, `formatDate`, `newIdempotencyKey`.
4. **`@keluargamart/api-client`** (`packages/api-client`):
   - Wrapper Axios terstandar dengan error handling (`ApiError`), request/response interceptors, dan token lifecycle.

---

## ⚙️ Prasyarat Sistem

- **Node.js**: `v20.x` atau `v22.x` (LTS direkomendasikan)
- **pnpm**: `v10.x` atau `v12.x` (`corepack enable && corepack prepare pnpm@latest --activate`)
- **Go**: `v1.23+` (untuk backend)
- **Python**: `v3.10+` (untuk script validation drift guard & nextreport)
- **Docker** atau **Podman**: untuk containerization & database orchestration

---

## ⚡ Quick Start

```bash
# 1. Clone repositori
git clone <repository-url> keluargamart-monorepo
cd keluargamart-monorepo

# 2. Salin environment template
cp .env.example .env

# 3. Install seluruh dependency workspace
pnpm install

# 4. Validasi API drift guard
pnpm drift:check

# 5. Jalankan backend & frontends
pnpm dev:backend   # Menjalankan Go backend di :8080
pnpm dev           # Menjalankan seluruh frontend via Turborepo
```

---

## 🛠️ Daftar Command Utama

### Orkestrasi Global (Turborepo)

| Command | Penjelasan |
|---|---|
| `pnpm dev` | Menjalankan seluruh frontend dev server secara paralel |
| `pnpm build` | Build seluruh shared packages dan frontend applications |
| `pnpm test` | Menjalankan seluruh unit test suite frontend & packages |
| `pnpm lint` | Menjalankan linter di seluruh workspace frontend |
| `pnpm typecheck` | Menjalankan static typechecking (Nuxt, dsb.) |

### Backend Go Commands

| Command | Penjelasan |
|---|---|
| `pnpm dev:backend` | Menjalankan server Go lokal (`apps/backend/cmd/server`) |
| `pnpm build:backend` | Mengompilasi Go binary ke `apps/backend/bin/server` |
| `pnpm test:backend` | Menjalankan Go test suite (`go test ./...`) |
| `pnpm lint:backend` | Menjalankan `golangci-lint` atau format check |

### Governance & Drift Guard

| Command | Penjelasan |
|---|---|
| `pnpm drift:check` | Memvalidasi kesesuaian routes & permissions antara backend, OpenAPI, dan `@keluargamart/*` |

### Targeted Sub-Workspace Execution

Jalankan task khusus untuk satu aplikasi menggunakan filter Turborepo:

```bash
# Development
pnpm --filter @keluargamart/erp dev
pnpm --filter @keluargamart/pos dev
pnpm --filter @keluargamart/b2b dev

# Build
pnpm --filter @keluargamart/b2b build
pnpm --filter @keluargamart/contracts build

# Test
pnpm --filter @keluargamart/permissions test
pnpm --filter @keluargamart/utils test
```

---

## 🛡️ API Contract & Permission Drift Guard

Monorepo ini menerapkan automated drift guard (`scripts/check-drift.py`) yang berjalan pada setiap pull request di CI/CD:

```bash
pnpm drift:check
```

Script ini memastikan bahwa:
1. Setiap endpoint di `apps/backend/docs/openapi.yaml` terdaftar di `packages/contracts/src/routes.txt`.
2. Setiap permission di `apps/backend/internal/modules/rbac/catalog.go` terdaftar di `packages/permissions/src/permissions.txt`.
3. Tidak ada client yang menggunakan rute atau permission yang telah usang atau tidak terdokumentasi.

---

## 🐳 Infrastruktur & Container

Konfigurasi runtime tersedia di direktori `infra/`:

- **Development Compose**: `apps/backend/docker-compose.dev.yml` (mengorkestrasi Postgres, Redis, MinIO, Mailpit, dan Frontend).
- **Unified Gateway**: `infra/reverse-proxy/Caddyfile` (menggabungkan backend `/api/*` dan frontends dalam satu host).
- **Production Compose**: `infra/containers/compose.yml`.

Jalankan container stack lokal:
```bash
docker compose -f apps/backend/docker-compose.dev.yml up -d
```

---

## 📚 Dokumentasi Lengkap

Dokumentasi arsitektur dan operasional tersedia di folder [`docs/`](./docs/):

- 📐 [Arsitektur Sistem](./docs/architecture/overview.md)
- 🔗 [Boundaries & Dependency Graph](./docs/architecture/boundaries-and-dependencies.md)
- 📜 [Kontrak API & Permission Catalog](./docs/architecture/contracts-and-governance.md)
- 🗃️ [Laporan Riwayat Migrasi Git](./docs/migration/polyrepo-to-monorepo.md)
- 📊 [Baseline vs Final Verification](./docs/migration/baseline-vs-final.md)
- 💻 [Panduan Developer](./docs/development/getting-started.md)
- ⚙️ [Panduan Turborepo](./docs/development/turborepo-guide.md)
- 🔄 [Alur Penambahan Endpoint Baru](./docs/development/api-workflow.md)
- 🌐 [Environment Variables Matrix](./docs/development/environment-matrix.md)
- 🚢 [Panduan Deployment & CI/CD](./docs/deployment/ci-cd.md)
- 🏛️ [Architecture Decision Records (ADR)](./docs/adr/)

---

## 🔧 Troubleshooting

### 1. Masalah Node / pnpm lockfile
Jika terjadi mismatch dependency setelah pull:
```bash
pnpm install --fix-lockfile
```

### 2. Phantom Dependencies
Monorepo menggunakan pnpm node-linker terisolasi. Jika modul tidak ditemukan saat runtime, pastikan dependensi dideklarasikan langsung di `package.json` sub-aplikasi yang bersangkutan, bukan mengandalkan hoisting.

### 3. Turborepo Cache Reset
Untuk membersihkan build cache Turborepo:
```bash
pnpm exec turbo clean
rm -rf .turbo apps/*/.turbo packages/*/.turbo
```