Modul 07: Arsitektur & Ekstensi - Kursus EUDR Forest Analyzer

Lihat Arsitektur Lengkap

Diagram interaktif ini menunjukkan setiap komponen utama dari EUDR Forest Analyzer dan bagaimana mereka terhubung. Klik komponen mana saja untuk mempelajari fungsinya dan di mana letaknya dalam codebase.

BROWSER

Dashboard

Halaman Auth

Panel Admin

▼ ▼ ▼

LAPISAN API (Router FastAPI)

API Analisis

API Auth

API Laporan

API Peringatan

API Antrian

API Admin

▼ ▼ ▼

SERVICES (Logika Bisnis)

Forest Analyzer

Layanan GLAD

Layanan RADD

Generator Laporan

Worker Antrian

Layanan Email

Citra Sentinel

Tutupan Lahan

▼ ▼ ▼

LAYANAN EKSTERNAL

Google Earth Engine

PostgreSQL + PostGIS

Email SMTP

Penyimpanan MinIO

Klik komponen mana saja untuk mempelajarinya.

Keputusan Desain Utama

Abstraksi Provider

Semua akses data satelit melalui factory pattern. Beralih dari Google Earth Engine ke Copernicus berarti mengubah satu variabel lingkungan, bukan menulis ulang layanan.

Antrian Asinkron

Analisis yang berjalan lama dialihkan ke worker latar belakang melalui antrian berbasis database. Pengguna mendapat respons langsung dengan ID pekerjaan, kemudian memantau atau menerima email saat hasil siap.

Sistem Peringatan Ganda

GLAD (optik, 30m) dan RADD (radar, 10m) berjalan secara paralel melalui asyncio.gather(). Radar bekerja menembus awan; optik memiliki riwayat lebih panjang. Validasi silang meningkatkan kepercayaan saat keduanya mendeteksi kehilangan.

Self-Healing

stuck_analysis_fixer berjalan setiap menit, mendeteksi analisis yang terjebak dalam status PROCESSING melampaui batas waktu. Secara otomatis mencoba ulang hingga 3 kali sebelum menandai sebagai ERROR, mencegah kegagalan diam.

Resep Ekstensi

Lima resep praktis untuk memperluas sistem. Masing-masing mengikuti pola yang ada sehingga perubahan Anda terintegrasi dengan baik.

Cara menambahkan provider data satelit baru

Contoh: menambahkan Planet Labs sebagai sumber data di samping GEE, Planetary Computer, dan CDSE.

Buat backend/providers/planet_provider.py. Impor dan perluas kelas dasar DataProvider dari providers/base.py.
Implementasikan semua 6 metode yang diperlukan: initialize(), get_forest_loss_alerts(), get_radar_alerts(), get_land_cover(), get_satellite_imagery(), dan get_ndvi_analysis(). Masing-masing harus menerima parameter geometri dan tanggal yang sama seperti interface dasarnya.
Buka backend/providers/factory.py. Tambahkan kasus baru ke logika pemilihan provider: if provider == "planet": return PlanetProvider().
Atur DATA_PROVIDER=planet di file .env Anda. Factory akan membuat provider Anda secara otomatis.
Tidak perlu perubahan di layanan, endpoint API, atau frontend. Lapisan abstraksi memastikan semua kode yang ada bekerja dengan provider mana pun yang mengimplementasikan interface tersebut.

Cara menambahkan sumber peringatan baru

Contoh: menambahkan sistem peringatan hipotetis FORMA di samping GLAD dan RADD.

Buat backend/services/forma_alert_service.py mengikuti pola glad_alert_service.py. Implementasikan metode yang menerima geometri dan rentang tanggal lalu mengembalikan data peringatan.
Buka backend/services/forest_analyzer_with_alerts.py. Di metode _analyze_alerts(), temukan pemanggilan asyncio.gather() di mana glad_task dan radd_task didefinisikan.
Tambahkan tugas baru Anda: forma_task = self.forma_service.get_alerts(geometry, start_date, end_date). Tambahkan ke pemanggilan asyncio.gather(glad_task, radd_task, forma_task).
Proses hasil FORMA dengan cara yang sama seperti hasil GLAD dan RADD diproses: periksa peringatan setelah tanggal batas EUDR dan tambahkan ke ringkasan gabungan.
Tambahkan endpoint API peringatan di backend/api/alerts.py untuk menanyakan peringatan FORMA secara langsung (opsional, untuk tampilan UI).

Cara menambahkan bagian laporan baru

Contoh: menambahkan bagian risiko air ke laporan PDF yang ditingkatkan.

Buka backend/services/report_generator.py. Buat metode baru _draw_water_risk_section(self, canvas, data).
Gunakan metode canvas ReportLab untuk menggambar bagian Anda: canvas.drawString() untuk teks, canvas.drawImage() untuk peta, canvas.setFont() untuk penataan gaya. Ikuti metode yang ada seperti _draw_biodiversity_section() untuk pola tata letak.
Tangani pemisahan halaman dengan memeriksa posisi Y saat ini. Jika konten Anda tidak muat, panggil canvas.showPage() dan reset header.
Di metode utama generate_compliance_report(), tambahkan pemanggilan ke metode baru Anda pada posisi yang diinginkan dalam urutan laporan.
Jika bagian Anda membutuhkan data, ambil di lapisan layanan (misalnya, enhanced_analysis_service.py) dan teruskan melalui dictionary data yang ada.

Cara menambahkan entitas API baru

Contoh: menambahkan entitas "Sertifikasi" untuk melacak sertifikasi keberlanjutan untuk plot.

Definisikan model data di backend/models/. Buat file baru atau tambahkan ke __init__.py: dataclass dengan field seperti id, plot_id, certification_type, issued_date, expiry_date.
Tambahkan tabel database di backend/utils/database.py. Tambahkan pernyataan CREATE TABLE IF NOT EXISTS certifications (...) ke fungsi pengaturan skema.
Buat router API di backend/api/certifications.py. Definisikan endpoint CRUD: POST /api/certifications, GET /api/certifications/{id}, GET /api/certifications/plot/{plot_id}, dll.
Daftarkan router di backend/app.py: impor router Anda dan tambahkan app.include_router(certifications_router, prefix="/api/certifications").

Cara deploy ke produksi

Sistem ini menyertakan file deployment Docker di direktori deploy/.

Konfigurasi semua variabel lingkungan di .env untuk produksi: kredensial service account GEE yang sebenarnya, host dan kata sandi PostgreSQL produksi, kredensial SMTP untuk email, dan endpoint MinIO.
Atur USE_REAL_FOREST_DATA=true dan sediakan file kunci service account GEE. Tanpa ini, sistem menggunakan data hutan simulasi.
Jalankan docker-compose up -d dari direktori deploy/. Ini memulai backend FastAPI, database PostgreSQL+PostGIS, dan penyimpanan MinIO.
Verifikasi deployment dengan memeriksa http://host-anda:8000/api/docs untuk Swagger UI dan menjalankan uji coba unggah analisis.
Untuk deployment GitHub Container Registry (ghcr.io), konfigurasi deploy sudah disiapkan. Push image Anda dan perbarui file compose dengan path registry Anda.

Wawasan Arsitektural

Lapisan Abstraksi

Sistem ini diorganisasikan ke dalam empat lapisan yang bersih. Setiap lapisan hanya berkomunikasi dengan tetangga terdekatnya, tidak pernah melompati level. Lapisan API tidak pernah menanyakan Google Earth Engine secara langsung -- ia memanggil layanan, yang memanggil provider. Ini membuat sistem dapat diuji (mock lapisan mana saja) dan dapat ditukar (ganti lapisan mana saja tanpa menyentuh yang lain).

Lapisan HTTP Router FastAPI mem-parsing request, memvalidasi input, meneruskan ke layanan

▼

Logika Bisnis Layanan mengimplementasikan aturan domain, analisis, penilaian

▼

Akses Data Model mendefinisikan bentuk data, database.py mengelola koneksi

▼

Layanan Eksternal Provider mengadaptasi API pihak ketiga (GEE, Planetary, CDSE)

Pelapisan ini berarti Anda dapat menguji logika bisnis tanpa database (mock lapisan akses data), menukar GEE dengan Planetary Computer tanpa menyentuh layanan (tukar provider-nya), atau mengganti FastAPI dengan framework lain tanpa mengubah logika bisnis apa pun.

Mengapa Bukan Microservices?

ⓘ

Sistem ini adalah monolit -- dan itu pilihan yang tepat.

Semua kode berjalan dalam satu proses. Tim-nya kecil, deployment-nya sederhana, dan layanan berbagi data melalui pemanggilan fungsi (cepat, type-safe) bukan pemanggilan HTTP (lambat, rapuh, perlu serialisasi). Microservices menambahkan kompleksitas jaringan, distributed tracing, service discovery, dan orkestrasi deployment yang hanya menguntungkan pada skala yang jauh lebih besar. Monolit yang terstruktur dengan baik dan memiliki batas lapisan yang bersih dapat dipecah menjadi microservices nanti jika diperlukan -- batas-batasnya sudah ada dalam kode.

Titik Ekstensi

Sistem ini dirancang untuk diperluas pada titik-titik yang spesifik dan terdefinisi dengan baik. Setiap titik ekstensi memiliki pola yang jelas untuk diikuti, sehingga fitur baru terintegrasi dengan bersih tanpa memodifikasi kode yang ada:

Provider data baru -- implementasikan interface DataProvider dan daftarkan di factory
Sumber peringatan baru -- tambahkan tugas ke pemanggilan asyncio.gather() di _analyze_alerts()
Bagian laporan baru -- tambahkan metode _draw dan panggil dari generate_compliance_report()
Entitas API baru -- buat router dan daftarkan di app.py
Fitur langganan baru -- tambahkan entri ke dictionary flag fitur di get_features()
Pekerjaan latar belakang baru -- mulai di startup_event() di app.py

Uji Pemahaman Anda

Q1: Anda perlu menambahkan Planet Labs sebagai provider satelit baru. Apa perubahan minimum yang diperlukan?

Q2: Klien menginginkan data Sentinel-2 dari sumber berbeda (bukan GEE). Konsep arsitektur apa yang memungkinkan ini?

Q3: Anda menambahkan sistem peringatan ketiga di samping GLAD dan RADD. Di mana Anda menambahkannya?

Referensi Arsitektur

Lapisan Sistem

Lapisan	Lokasi	Tanggung Jawab	Contoh
HTTP	`backend/api/`	Mem-parsing request, memvalidasi input, meneruskan ke layanan	`analysis.py`
Logika Bisnis	`backend/services/`	Aturan domain, analisis, penilaian	`forest_analyzer_with_alerts.py`
Model Data	`backend/models/`	Mendefinisikan bentuk data dan enum	`ComplianceStatus`, `RiskLevel`
Akses Data	`backend/utils/`	Koneksi database, query	`database.py`
Eksternal	`backend/providers/`	Adapter API pihak ketiga	`gee_provider.py`

Titik Ekstensi

Yang Ditambahkan	Di Mana	Pola
Provider data baru	`providers/` + `factory.py`	Implementasikan interface `DataProvider`
Sumber peringatan baru	`services/` + `_analyze_alerts()`	Tambahkan ke `asyncio.gather()`
Bagian laporan baru	`report_generator.py`	Tambahkan metode `_draw` + panggil
Entitas API baru	`api/` + `models/` + `app.py`	Buat router + daftarkan
Fitur langganan baru	`models/user.py`	Tambahkan ke dictionary `get_features()`
Pekerjaan latar belakang baru	`services/` + startup `app.py`	Mulai di `startup_event()`

Tech Stack

Teknologi	Tujuan	Alasan Dipilih
FastAPI	Framework web	Dukungan async, dokumentasi otomatis, validasi tipe
PostgreSQL + PostGIS	Database	Query spasial pada data geografis
Google Earth Engine	Data satelit	Dataset skala petabyte, pemrosesan cloud
ReportLab	Pembuatan PDF	Kontrol penuh atas tata letak dan citra
JWT (python-jose)	Autentikasi	Token stateless, dukungan refresh
psycopg2	Driver DB	Connection pooling, dict cursor
Shapely	Pemrosesan geometri	Validasi/perbaikan poligon

Kursus Selesai

Anda telah menyelesaikan ketujuh modul kursus EUDR Forest Analyzer. Anda sekarang memahami bagaimana sistem ini dibangun, bagaimana data mengalir melaluinya, dan bagaimana memperluasnya untuk kebutuhan baru.

Berikut yang telah Anda pelajari:

Ikhtisar Proyek Arsitektur Backend Aliran Data Analisis Geospasial Autentikasi Laporan & Peringatan Arsitektur & Ekstensi