merica/docs/architecture.md

# 🏛️ 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)