feat(release): prepare clean public open-source MERICA pipeline bundles repository

2026-10-09 01:01:44 +07:00
parent 42fedab752
commit 3aa0d15462
6 changed files with 468 additions and 71 deletions
@@ -1,96 +1,119 @@
-# 🌊 MERICA Pipeline Bundles (Release Delivery v1.0)
+# 📦 MERICA Pipeline Bundles (Public Open-Source Data Lakehouse Assets)

-> **Declarative Lakehouse Pipelines, dbt Transformations, and Data Contracts**  
-> *Repositori Resmi Definisi Data Pipeline untuk Pengguna / Data Engineer (Self-Hosted Git Delivery).*
+> **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
+## 🏛️ 1. Ikhtisar Repositori

-Repositori **`merica-pipeline`** adalah **Single Source of Truth (SSOT)** untuk seluruh definisi pipeline data, model transformasi dbt, aturan tata kelola metadata, dan pengujian kualitas data pada platform **MERICA Data Lakehouse**.
+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.

-Melalui arsitektur **Git DAG Bundles (AIP-66)** Apache Airflow 3, setiap berkas konfigurasi YAML di repositori ini secara otomatis disinkronkan ke Airflow runtime dalam interval **30 detik** tanpa memerlukan restart layanan atau penyalinan berkas manual ke server 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
+## 📁 2. Struktur Direktori Repositori

 ```text
-release/merica-pipeline/
-├── configs/                    # Deklarasi pipeline ingestion kanonikal (YAML)
-│   ├── example_permits_medallion_dbt_postgres.yaml # Referensi End-to-End Medallion dbt
-│   ├── ingestion_api_spku_air_quality.yaml          # IoT Real-time Air Quality (Sliding Window)
+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 Workspace Spreadsheet Sanitizer
-├── dbt/                        # Transformasi Medallion data mart (SQL)
+│   └── 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/             # Model pembersihan & deduplikasi
-│       └── gold/               # Model data mart & kepatuhan pelaporan
-├── metadata/                   # JSON metadata tata kelola OpenMetadata
-│   ├── example_permits_medallion_dbt_postgres.json
-│   └── ingestion_api_spku_air_quality.json
-├── schemas/                    # Kontrak skema JSON & validator
-├── samples/                    # Sampel dummy dataset untuk pengujian
-│   ├── waste_reports_raw.csv   # Sampel CSV kotor
-│   ├── spku_realtime.json      # Sampel JSON sensor IoT
-│   └── seed_amdal_permits.sql  # SQL seed data transaksional
-├── docs/                       # Panduan penulisan pipeline untuk Data Engineer
-│   ├── pipeline_specifications.md
-│   ├── dbt_modeling_guide.md
-│   └── adding_new_pipeline.md
-└── README.md                   # Panduan utama repositori pipeline
+│       ├── 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)
+## 📋 3. Katalog 4 Pipeline Bawaan (Canonical Use Cases)

-| Nama Pipeline | File Konfigurasi | Engine & Operator | Lapisan Medallion |
+| Nama Pipeline | Domain | Jadwal | Engine & Alur Medallion |
 | :--- | :--- | :--- | :--- |
-| **AMDAL CDC Ingestion** | `ingestion_db_environmental_permits_cdc.yaml` | Sling CLI Log-Based CDC | PostgreSQL ➔ Bronze S3 (Parquet) |
-| **GWS Waste Reports** | `ingestion_gws_waste_reports.yaml` | GWS Sanitizer Operator | Google Sheets ➔ Bronze Parquet |
-| **SPKU IoT Air Quality** | `ingestion_api_spku_air_quality.yaml` | REST API Sliding Window | HTTP REST ➔ Bronze S3 (JSON) |
-| **Reference Medallion dbt** | `example_permits_medallion_dbt_postgres.yaml` | Sling + Great Expectations + dbt | Bronze ➔ Silver ➔ Gold Marts |
+| `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. Panduan Menambahkan Pipeline Baru
+## ⚙️ 4. Cara Penggunaan Bersama MERICA Standalone Appliance

-Untuk menambahkan pipeline baru ke dalam sistem:
+Cukup arahkan variabel lingkungan di `.env` file **MERICA Standalone** ke URL repositori ini:

-1. **Buat Berkas Konfigurasi YAML di Direktori `configs/`**:
-   Contoh: `configs/ingestion_my_dataset.yaml`
-   ```yaml
-   pipeline_id: "ingestion_my_dataset"
-   description: "Pipeline Ingestion Data Operasional Baru"
-   schedule_interval: "@daily"
-   tags: ["operational", "bronze"]
-   source:
-     type: "postgres"
-     connection_id: "conn_postgres_source_db"
-     table: "public.my_table"
-   target:
-     bucket: "dlh-bronze"
-     format: "parquet"
-   ```
+```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

-2. **(Opsional) Tambahkan Transformasi dbt di Direktori `dbt/models/`**:
-   Tambahkan file SQL di `silver/` atau `gold/` untuk mendefinisikan agregasi analitik.
+# Karena repositori ini publik/open, kosongkan kredensial git:
+GIT_PIPELINE_REPO_USER=
+GIT_PIPELINE_REPO_TOKEN=
+```

-3. **Commit & Push ke Server Git**:
+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/ingestion_my_dataset.yaml
-   git commit -m "feat(pipeline): add new operational dataset pipeline"
+   git add configs/<nama_pipeline>.yaml
+   git commit -m "feat(pipeline): add new pipeline"
   git push origin main
   ```
-
-4. **Verifikasi di Airflow Webserver (Port 14080)**:
-   Dalam waktu maksimum 30 detik, DAG baru dengan ID `dag_ingestion_my_dataset` akan muncul otomatis di antarmuka Airflow tanpa restart scheduler!
+4. **Selesai**: Dalam waktu 30 detik, DAG baru langsung aktif dan terdeteksi di Airflow dan MERICA Studio.

 ---

-## 📚 5. Dokumentasi Teknis Terkait
+## 🧪 6. Menjalankan Unit Tests Lokal

-* 📑 [docs/pipeline_specifications.md](docs/pipeline_specifications.md) — Spesifikasi lengkap schema sintaksis YAML pipeline.
-* 🧊 [docs/dbt_modeling_guide.md](docs/dbt_modeling_guide.md) — Panduan pemodelan data Medallion (Bronze, Silver, Gold).
-* 🚀 [docs/adding_new_pipeline.md](docs/adding_new_pipeline.md) — Tutorial langkah-demi-langkah bagi Data Engineer.
+```bash
+pip install -r requirements.txt
+pytest tests/ -v
+```
+
+---
+
+## 📄 Lisensi
+
+Proyek ini dilisensikan di bawah ketentuan [Apache License 2.0](LICENSE).