merica/docs/architecture.md

🏛️ Arsitektur Platform — MERICA

Navigasi Cepat: 🏠 Pusat Dokumentasi | 📦 Panduan Deployment | 📘 Integrasi Airflow External | 🎨 Panduan Pengguna Canvas

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

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:

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
• Menghubungkan ke Airflow: 📘 Panduan Integrasi Airflow External
• Memulai Mendesain Pipeline: 🎨 Panduan Pengguna Canvas
• Kembali ke Indeks: 🏠 Pusat Dokumentasi