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

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.
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.
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.
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

    ROUTERS --> SERVICES

Modul-Modul Utama:

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.
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).
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.
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).
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

8.1 KiB Raw Blame History

🏛️ Arsitektur Platform — MERICA

📌 1. Prinsip Utama Rancang Bangun

🌐 2. Diagram Topologi Kontainer & Aliran Jaringan

🧩 3. Arsitektur Internal Modul Backend (Engine Core)

Modul-Modul Utama:

🔒 4. Keamanan Perimeter & Kebijakan Hak Akses

🧭 Navigasi Dokumen Terkait

8.1 KiB

Raw Blame History