merica-pipelines/README.md

# 📦 MERICA Pipeline Bundles (Data Lakehouse Production Assets)

> **Repositori Resmi**: **Single Source of Truth (SSOT)** Aset Konfigurasi Pipeline, Model dbt Medallion, Metadata, & Custom Operators untuk **MERICA Data Lakehouse**  
> **Status**: **General Availability (GA) v1.0 — Production Ready**  
> **Integrasi Platform**: Apache Airflow 3 Native Git DAG Bundles (`GitDagBundle` AIP-66) & dbt Core  

---

## 🏛️ 1. Ikhtisar Repositori

Repositori **`merica-pipelines`** adalah **Single Source of Truth (SSOT)** yang mengisolasi seluruh logika bisnis pipeline data dan model analitik dari runtime engine platform MERICA Studio dan Apache Airflow.

Dengan arsitektur **Git DAG Bundles (AIP-66)** Apache Airflow 3:
* **Sinkronisasi Otomatis Tanpa Restart**: Setiap berkas konfigurasi YAML di repositori ini secara otomatis disinkronkan ke Airflow runtime dalam interval **30 detik** tanpa mematikan atau me-restart scheduler/webserver.
* **Canvas Interaktif MERICA Studio**: Konfigurasi YAML di repositori ini langsung dibaca dan dirender menjadi node-edge pipeline pada antarmuka visual MERICA Studio Canvas.
* **Distribusi Terpusat**: Pengguna appliance MERICA Studio cukup mengarahkan URL repositori ini pada konfigurasi lingkungan untuk mendapatkan katalog pipeline terbaru.

---

## 📁 2. Struktur Direktori Repositori

```text
merica-pipelines/
├── README.md                       # Dokumentasi utama repositori
├── TESTING.md                      # Panduan audit dan validasi aset pipeline
├── requirements.txt                # Dependensi testing Python (pytest, ruff)
├── configs/                        # Konfigurasi pipeline deklaratif (*.yaml)
│   ├── example_permits_medallion_dbt_postgres.yaml # Referensi E2E Medallion dbt
│   ├── ingestion_api_spku_air_quality.yaml          # IoT Real-time Air Quality
│   ├── ingestion_db_environmental_permits_cdc.yaml  # DB Transactional CDC (Sling)
│   └── ingestion_gws_waste_reports.yaml             # Google Sheets Extractor & Sanitizer
├── dags/                           # Airflow 3 DAG Factory & Custom Operators
│   ├── dag_factory.py              # Dynamic DAG generator berbasis YAML deklaratif
│   └── helpers/                    # Multi-engine execution operators
│       ├── base_lakehouse_operator.py
│       ├── duckdb_operator.py
│       ├── pyiceberg_operator.py
│       ├── pyspark_operator.py
│       ├── ge_lakehouse_operator.py
│       ├── dbt_trino_operator.py
│       ├── sling_helper.py
│       ├── storage_helper.py
│       ├── api_helper.py
│       ├── gws_helper.py
│       ├── merica_alert_hook.py
│       └── sitomat_callback_operator.py
├── dbt/                            # Model SQL dbt Core Medallion
│   ├── dbt_project.yml             # Konfigurasi dbt project
│   ├── profiles.yml                # Koneksi profile dbt
│   └── models/
│       ├── silver/                 # Deduplikasi CDC & Data Cleansing
│       └── gold/                   # Data Mart, ISPU harian, & Agregasi KPI
├── metadata/                       # Metadata visual posisi node kanvas (*.json)
├── samples/                        # Dataset referensi untuk validasi lokal
├── schemas/                        # Kontrak skema dataset (.gitkeep)
├── docs/                           # Panduan teknis spesifikasi pipeline
└── tests/                          # Automated unit tests untuk seluruh operator
```

---

## 📋 3. Katalog Pipeline Kanonikal

| Nama Pipeline | Domain | Jadwal | Engine & Alur Medallion |
| :--- | :--- | :--- | :--- |
| `example_permits_medallion_dbt_postgres` | Perizinan Lingkungan | `0 8 * * *` | **E2E Medallion**: Sling CDC $\rightarrow$ GE Bronze $\rightarrow$ dbt Silver $\rightarrow$ GE Silver $\rightarrow$ dbt Gold $\rightarrow$ Callback. |
| `ingestion_db_environmental_permits_cdc` | AMDAL / UKL-UPL | `0 */2 * * *` | **Log CDC**: Replikasi intensif Postgres DB $\rightarrow$ S3 Bronze Parquet $\rightarrow$ DuckDB Silver $\rightarrow$ dbt Gold. |
| `ingestion_api_spku_air_quality` | Kualitas Udara (SPKU) | `0 4 * * *` | **Sliding Window**: REST API JSON $\rightarrow$ Bronze S3 $\rightarrow$ DuckDB Iceberg $\rightarrow$ GE Suite $\rightarrow$ dbt Gold Mart. |
| `ingestion_gws_waste_reports` | Sampah & Limbah B3 | `0 4 * * *` | **GWS Sanitizer**: Google Sheets $\rightarrow$ Sanitasi Regex $\rightarrow$ S3 Bronze $\rightarrow$ PyIceberg Silver $\rightarrow$ dbt Gold. |

---

## ⚙️ 4. Cara Penggunaan Bersama MERICA Studio Appliance

Arahkan variabel lingkungan di `.env` file **MERICA Studio / Standalone** ke URL repositori ini:

```bash
# Konfigurasi repositori pipeline di .env:
GIT_PIPELINE_REPO_URL=https://repo.sicabe.com/merica-dlh/merica-pipelines.git
GIT_PIPELINE_REPO_BRANCH=main
GIT_PIPELINE_REPO_SUBDIR=dags

# Kredensial repositori git (kosongkan jika repositori dapat diakses tanpa autentikasi):
GIT_PIPELINE_REPO_USER=
GIT_PIPELINE_REPO_TOKEN=
```

Ketika stack MERICA Studio dijalankan (`./scripts/01_install_stack.sh`), Airflow 3 DAG Processor akan otomatis mengunduh repositori ini dan menyajikan seluruh DAG pada antarmuka web Airflow ([http://localhost:14080](http://localhost:14080)) serta MERICA Studio Canvas ([http://localhost:14000](http://localhost:14000)).

---

## 🛠️ 5. Menambahkan Pipeline Baru

1. **Tambahkan berkas konfigurasi YAML** di direktori `configs/<nama_pipeline>.yaml`.
2. **(Opsional) Tambahkan model dbt** di direktori `dbt/models/silver/` atau `dbt/models/gold/`.
3. **Commit & Push**:
   ```bash
   git add configs/<nama_pipeline>.yaml
   git commit -m "feat(pipeline): add new pipeline"
   git push origin main
   ```
4. **Verifikasi**: Dalam waktu 30 detik, pipeline baru akan terdeteksi dan aktif secara otomatis di Airflow dan MERICA Studio.

---

## 🧪 6. Pengujian Unit Lokal

```bash
pip install -r requirements.txt
pytest tests/ -v
```