# 📦 MERICA Pipeline Bundles (Public Open-Source Data Lakehouse 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 & Open-Source**  
> **Standar Integrasi**: Apache Airflow 3 Native Git DAG Bundles (`GitDagBundle` AIP-66) & dbt Core  

---

## 🏛️ 1. Ikhtisar Repositori

Repositori **`merica-pipeline`** adalah **Single Source of Truth (SSOT)** publik yang memisahkan seluruh logika bisnis data pipelines dari runtime platform MERICA Studio dan Airflow Engine.

Dengan arsitektur **Git DAG Bundles (AIP-66)** Apache Airflow 3:
* **Zero-Credential / Anonymous Clone**: Karena repositori ini bersifat publik/open, Airflow 3 DAG Processor dapat melakukan kloning dan sinkronisasi otomatis tanpa memerlukan username, password, atau personal access token (PAT).
* **Hot-Reload 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 divisualisasikan menjadi node-edge pipeline di antarmuka web MERICA Studio Canvas.

---

## 📁 2. Struktur Direktori Repositori

```text
merica-pipeline/
├── LICENSE                         # Lisensi Apache 2.0 Open-Source
├── README.md                       # Dokumentasi utama repositori
├── RELEASE_NOTES.md                # Catatan rilis resmi v1.0 GA
├── TESTING.md                      # Panduan pengujian lokal & CI/CD
├── 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/                        # Dummy sample dataset untuk validasi lokal
├── schemas/                        # Kontrak skema dataset (.gitkeep)
├── docs/                           # Panduan teknis penulisan pipeline
└── tests/                          # Automated unit tests untuk seluruh operator
```

---

## 📋 3. Katalog 4 Pipeline Bawaan (Canonical Use Cases)

| 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 Standalone Appliance

Cukup arahkan variabel lingkungan di `.env` file **MERICA Standalone** ke URL repositori ini:

```bash
# Di dalam merica-standalone/.env:
GIT_PIPELINE_REPO_URL=https://github.com/<your-username-or-org>/merica-pipeline.git
GIT_PIPELINE_REPO_BRANCH=main
GIT_PIPELINE_REPO_SUBDIR=dags

# Karena repositori ini publik/open, kosongkan kredensial git:
GIT_PIPELINE_REPO_USER=
GIT_PIPELINE_REPO_TOKEN=
```

Ketika stack MERICA Standalone dinyalakan (`./scripts/01_install_stack.sh`), Airflow 3 DAG Processor akan otomatis meng-clone repositori ini dan menyajikan seluruh DAG di web UI ([http://localhost:14080](http://localhost:14080)) serta di MERICA Studio Canvas ([http://localhost:14000](http://localhost:14000)).

---

## 🛠️ 5. Menambahkan Pipeline Baru

1. **Tambahkan file konfigurasi YAML** di `configs/<nama_pipeline>.yaml`.
2. **(Opsional) Tambahkan model dbt** di `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. **Selesai**: Dalam waktu 30 detik, DAG baru langsung aktif dan terdeteksi di Airflow dan MERICA Studio.

---

## 🧪 6. Menjalankan Unit Tests Lokal

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

---

## 📄 Lisensi

Proyek ini dilisensikan di bawah ketentuan [Apache License 2.0](LICENSE).