155 lines
8.2 KiB
Markdown
155 lines
8.2 KiB
Markdown
# 🏛️ Arsitektur Platform — MERICA
|
|
|
|
> **Navigasi Cepat**: [🏠 Pusat Dokumentasi](index.md) | [📦 Panduan Deployment](deployment_guide.md) | [📘 Integrasi Airflow External](panduan_integrasi_existing_airflow.md) | [🎨 Panduan Pengguna Canvas](user_guide.md)
|
|
|
|
Dokumen ini menjelaskan rancang bangun teknis distribusi produksi **MERICA Low-Code Appliance**.
|
|
|
|
---
|
|
|
|
## 📌 1. Prinsip Utama Rancang Bangun
|
|
|
|
1. **Pola Single-Port Appliance (Unified Ingress Gateway)**:
|
|
* Seluruh lalu lintas dari klien (peramban pengguna maupun panggilan REST API) disatukan melalui **port tunggal host: `14000`**.
|
|
* Di dalam kontainer, proses **Nginx** bertindak sebagai *reverse proxy gateway*:
|
|
* Permintaan UI (`/*`) disajikan langsung dari berkas statis Vite React (`/usr/share/nginx/html`).
|
|
* Permintaan API (`/api/*`), dokumentasi Swagger (`/docs`), dan skema (`/openapi.json`) di-proxy ke loopback backend FastAPI pada `127.0.0.1:8000`.
|
|
* **Port backend (8000) TIDAK PERNAH diekspos ke host luar**. Hal ini menjamin **Zero CORS Issues**, meminimalkan latensi jaringan internal, dan mengeliminasi vektor serangan langsung ke server aplikasi.
|
|
|
|
2. **Decoupled Stateless Engine & Zero Local Bloat**:
|
|
* Kontainer MERICA tidak menjalankan PostgreSQL, Redis, atau Airflow worker di dalamnya.
|
|
* Total penggunaan sumber daya appliance sangat efisien: **RAM $\sim$ 100 MB** dan **CPU idle $< 1\%$**.
|
|
* State eksekusi dan metadata pipeline dialokasikan sepenuhnya ke kluster Apache Airflow dan PostgreSQL eksternal yang dikonfigurasi melalui berkas `.env`.
|
|
|
|
3. **Dukungan Dual-Mode Pipelines SSOT (Starter Pipelines & GitOps)**:
|
|
* **Mode A: Local Mount Starter Pipelines** (`PIPELINES_DIR=./pipelines`): Menyediakan 3 template pipeline siap pakai secara *out-of-the-box* sehingga daftar pipeline langsung tersedia.
|
|
* **Mode B: Git DAG Bundles (AIP-66)**: Airflow DAG Processor secara mandiri memantau repositori Git pipeline (`merica-pipelines.git`) setiap 30 detik untuk *Zero-Downtime Hot-Reload*.
|
|
|
|
4. **Shift-Left Pre-Flight Verification**:
|
|
* Sebelum sebuah pipeline di-deploy ke Apache Airflow, engine backend MERICA menjalankan validasi sintaks `#val`, verifikasi kontrak kolom dbt (`contract: enforced`), dan inferensi tipe data otomatis. Kesalahan konfigurasi terdeteksi di kanvas sebelum task sempat dijadwalkan oleh scheduler Airflow.
|
|
|
|
---
|
|
|
|
## 🌐 2. Diagram Topologi Kontainer & Aliran Jaringan
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph CLIENT ["Akses Pengguna & Klien"]
|
|
USER["Pengguna / Browser Web\n(Data Engineer)"]
|
|
end
|
|
|
|
subgraph APPLIANCE ["MERICA Appliance Container (Port 14000:80)"]
|
|
NGINX["Nginx Web Gateway\n(Port 80 Internal)"]
|
|
REACT["Vite React Canvas UI\n(Static Assets / SPA)"]
|
|
FASTAPI["FastAPI Backend Engine\n(127.0.0.1:8000 Loopback)"]
|
|
SUPERVISOR["Supervisord Process Manager"]
|
|
|
|
NGINX -->|"/* Static Assets"| REACT
|
|
NGINX -->|"/api/* Reverse Proxy"| FASTAPI
|
|
SUPERVISOR -.->|"Supervisi Proses"| NGINX
|
|
SUPERVISOR -.->|"Supervisi Proses"| FASTAPI
|
|
end
|
|
|
|
subgraph PIPELINE_STORAGE ["Single Source of Truth (SSOT) Pipelines"]
|
|
LOCAL_MOUNT["Mounted Starter Pipelines\n(./pipelines/)"]
|
|
GIT_REPO["Git Pipeline Repository\n(merica-pipelines.git)"]
|
|
end
|
|
|
|
subgraph AIRFLOW_CLUSTER ["Apache Airflow 3 Cluster (External)"]
|
|
API_SERVER["Airflow API Server & Web UI\n(Port 14080)"]
|
|
SCHEDULER["Airflow Scheduler & Workers"]
|
|
DAG_PROC["Airflow DAG Processor\n(AIP-66 Git DAG Bundles)"]
|
|
end
|
|
|
|
subgraph EXTERNAL_LAKEHOUSE ["Infrastruktur Data Lakehouse (External)"]
|
|
PG_DB["PostgreSQL MetaDB\n(Port 14432)"]
|
|
S3_STORAGE["MinIO / S3 Lakehouse Storage\n(Port 14090)"]
|
|
OMD["OpenMetadata 2.0 Governance\n(Port 14585)"]
|
|
end
|
|
|
|
USER -->|"HTTP :14000"| NGINX
|
|
FASTAPI <-->|"Read / Write YAML & dbt"| LOCAL_MOUNT
|
|
FASTAPI -.->|"Push Commit (GitOps)"| GIT_REPO
|
|
FASTAPI -->|"REST API :14080"| API_SERVER
|
|
FASTAPI -->|"Introspection & Safe Preview"| PG_DB
|
|
FASTAPI -->|"Governance Entity Sync"| OMD
|
|
|
|
DAG_PROC -->|"Poll 30s Hot-Reload"| GIT_REPO
|
|
DAG_PROC <-->|"Local Volume Share"| LOCAL_MOUNT
|
|
SCHEDULER -->|"Eksekusi Task Ingestion"| PG_DB
|
|
SCHEDULER -->|"Parquet / Iceberg Write"| S3_STORAGE
|
|
SCHEDULER -->|"OpenLineage Telemetry"| OMD
|
|
```
|
|
|
|
---
|
|
|
|
## 🧩 3. Arsitektur Internal Modul Backend (Engine Core)
|
|
|
|
Backend MERICA dibangun di atas FastAPI modern dengan modul-modul modular:
|
|
|
|
```mermaid
|
|
graph LR
|
|
subgraph ROUTERS ["API Endpoints (/api/v1)"]
|
|
R_PIPE["pipelines.py\n(CRUD & Deploy)"]
|
|
R_DISC["discovery.py\n(GWS Explorer)"]
|
|
R_PREV["preview.py\n(DB Safe Preview)"]
|
|
R_VAL["validation.py\n(Pre-Flight Check)"]
|
|
R_GOV["governance.py\n(OpenMetadata)"]
|
|
end
|
|
|
|
subgraph SERVICES ["Core Business Services"]
|
|
S_PARSE["pipeline_parser.py\n(YAML Parser & Compiler)"]
|
|
S_DBT["dbt_service.py\n(Model Gen & Smart Types)"]
|
|
S_GWS["gws_service.py\n(Drive & Header Suggestion)"]
|
|
S_DB["db_service.py\n(Introspection & PK Detect)"]
|
|
S_AIR["airflow_service.py\n(Airflow 3 REST Client)"]
|
|
S_OMD["omd_service.py\n(OpenMetadata Registrasi)"]
|
|
end
|
|
|
|
R_PIPE --> S_PARSE
|
|
R_PIPE --> S_DBT
|
|
R_DISC --> S_GWS
|
|
R_PREV --> S_DB
|
|
R_VAL --> S_AIR
|
|
R_GOV --> S_OMD
|
|
```
|
|
|
|
### Modul-Modul Utama:
|
|
1. **Pipeline Parser & Compiler (`pipeline_parser.py`)**:
|
|
* Mengonversi skema visual ReactFlow (node & edge JSON) ke spesifikasi deklaratif YAML Airflow 3 (`configs/*.yaml`).
|
|
* Mengompilasi konfigurasi node menjadi parameter terstandarisasi untuk Sling CDC, GWS Ingestor, dlt REST API, DuckDB deduplikasi, dan Great Expectations.
|
|
2. **dbt Medallion Service (`dbt_service.py`)**:
|
|
* Menghasilkan model SQL dbt Silver dan Gold secara otomatis.
|
|
* **Smart DDL Type Inference**: Menginferensi tipe data kolom secara otomatis (`INTEGER`, `DECIMAL(18,2)`, `TIMESTAMP`, `VARCHAR`).
|
|
* **Shift-Left Quality Contract**: Menghasilkan aturan `schema.yml` dengan `contract: enforced`, constraint `unique`, `not_null`, dan `accepted_values`.
|
|
* **Astronomer Cosmos Adapter**: Menyusun TaskGroup Airflow 3 dengan perilaku `TestBehavior.AFTER_EACH` (memisahkan model `.run` dan `.test` secara granular).
|
|
3. **Database Introspection & Preview (`db_service.py`)**:
|
|
* Melakukan inspeksi skema tabel dari sumber PostgreSQL.
|
|
* Otomatis mendeteksi kandidat Primary Key (PK) dan kolom watermark berbasis timestamp.
|
|
* Menyediakan **Safe 10-Row Data Preview** menggunakan pembatasan `LIMIT 10` dan statement timeout untuk mencegah *table lock*.
|
|
4. **Google Workspace Discovery (`gws_service.py`)**:
|
|
* Menjelajahi folder Google Drive secara interaktif.
|
|
* Menganalisis tab Google Spreadsheet dan memberikan saran baris header (*Header Row Suggestion*).
|
|
* Menyiapkan konfigurasi pembersihan otomatis (*auto-cleansing*: nama kolom `snake_case`, pembersihan unit string `(Rp)`, forward-fill sel yang di-merge).
|
|
5. **OpenMetadata Governance Sync (`omd_service.py`)**:
|
|
* Sinkronisasi entitas pipeline ke katalog OpenMetadata 2.0.
|
|
* Pemetaan lineage visual end-to-end dari sumber data hingga Gold table.
|
|
* Integrasi hasil uji kualitas data Great Expectations ke tab Data Quality OpenMetadata.
|
|
|
|
---
|
|
|
|
## 🔒 4. Keamanan Perimeter & Kebijakan Hak Akses
|
|
|
|
* **UID Execution**: Apache Airflow berjalan dengan user ID **`50000:0` (airflow)** sesuai standar resmi Apache Airflow 3.
|
|
* **Volume Permission**: Seluruh volume bersama (*shared volumes*) yang diakses oleh DAG Processor menggunakan hak akses `50000:0` dengan `umask 0002` untuk mencegah *PermissionDenied error*.
|
|
* **Perimeter Network**: Port 8000 FastAPI hanya mendengarkan pada antarmuka lokal `127.0.0.1` di dalam kontainer appliance; peramban eksternal hanya dapat berkomunikasi melalui Nginx pada port `14000`.
|
|
* **Kredensial Aman**: Seluruh koneksi ke sumber database eksternal dan S3 menggunakan environment variable terenkripsi tanpa menyimpan *plain-text credential* di repositori Git.
|
|
|
|
---
|
|
|
|
## 🧭 Navigasi Dokumen Terkait
|
|
|
|
* Lanjutkan ke: [📦 Panduan Deployment & Build](deployment_guide.md)
|
|
* Menghubungkan ke Airflow: [📘 Panduan Integrasi Airflow External](panduan_integrasi_existing_airflow.md)
|
|
* Memulai Mendesain Pipeline: [🎨 Panduan Pengguna Canvas](user_guide.md)
|
|
* Kembali ke Indeks: [🏠 Pusat Dokumentasi](index.md)
|