Modul 02: Para Aktor Utama — Kursus EUDR Forest Analyzer

Kenali Setiap Komponen dengan Membaca Kodenya

Tutorial ini memandu Anda menelusuri komponen-komponen utama sistem, satu per satu. Di akhir tutorial, Anda akan mengetahui apa yang dilakukan setiap bagian, di mana letaknya, dan bagaimana hubungannya dengan bagian lain.

Langkah 1

Pintu Depan — `app.py`

app.py adalah tempat aplikasi dimulai. File ini membuat objek aplikasi FastAPI, mengimpor 13 router, mendaftarkan masing-masing dengan app.include_router(), mengatur CORS middleware, memasang file statis untuk frontend, dan mendefinisikan startup event yang menginisialisasi database, penjadwal alert, worker antrian, dan perbaikan analisis macet.

Buka file tersebut dan lihat bagian atas:

          backend/app.py
# Import router
from api.analysis import router as analysis_router
from api.auth import router as auth_router
from api.reports import router as reports_router
from api.dashboard import router as dashboard_router
from api.batch import router as batch_router
from api.queue import router as queue_router
from api.alerts import router as alerts_router
from api.suppliers import router as suppliers_router
from api.plots import router as plots_router
from api.organizations import router as organizations_router
from api.metrics import router as metrics_router
from api.supply_chain import router as supply_chain_router
from routes.enhanced_analysis import router as enhanced_analysis_router

# Setiap router didaftarkan dengan prefix URL
app.include_router(analysis_router, prefix="/api/analysis")
app.include_router(auth_router, prefix="/api/auth")
app.include_router(alerts_router, prefix="/api/alerts")
# ... dan seterusnya untuk semua 13 router
        

Sekarang lihat startup event:

          backend/app.py
@app.on_event("startup")
async def startup_event():
    # 1. Koneksi ke PostgreSQL + PostGIS
    await init_database()

    # 2. Mulai penjadwal alert (pemeriksaan GLAD/RADD berkala)
    start_alert_scheduler()

    # 3. Mulai worker antrian analisis async
    start_queue_worker()

    # 4. Mulai perbaikan analisis macet (auto-retry job terhenti)
    start_stuck_analysis_fixer()
        

Yang seharusnya Anda lihat: app.py murni merupakan file penghubung. File ini tidak mengandung logika bisnis — hanya menghubungkan semua bagian dan memulai layanan latar belakang.

Langkah 2

File Processor

file_processor_simple.py bertanggung jawab untuk memvalidasi dan mengurai unggahan. Ketika pengguna mengirimkan file geospasial, komponen ini mengambil alih. Komponen ini menerima tiga format file: GeoJSON, KML, dan Shapefile ZIP.

Salah satu fitur terpentingnya adalah perbaikan otomatis. Jika geometri yang diunggah tidak valid (poligon yang saling berpotongan, ring yang tidak tertutup), processor memanggil shapely.make_valid() untuk memperbaikinya secara diam-diam daripada menolak unggahan.

Processor mengembalikan objek PlotData yang berisi:

geometry — geometri GeoJSON yang telah divalidasi/diperbaiki
feature_count — jumlah fitur dalam file
total_area_hectares — total luas semua fitur
bounds — bounding box geometri

Poin penting: File processor adalah penjaga gerbang. Tidak ada yang masuk ke sistem tanpa melewatinya, dan ia memastikan setiap geometri valid sebelum analisis dimulai.

Langkah 3

Forest Analyzer

forest_analyzer_with_alerts.py (45KB) adalah otak dari seluruh sistem. Ini adalah bagian logika bisnis terbesar dan komponen yang mengubah data mentah menjadi keputusan kepatuhan EUDR.

Komponen ini menggabungkan empat sumber data menjadi satu hasil:

Data hutan GEE — Hansen Global Forest Change untuk persentase tutupan hutan
Alert GLAD — deteksi deforestasi optik (Landsat, 30m)
Alert RADD — deteksi deforestasi radar (Sentinel-1, 10m)
Risiko negara — daftar negara berisiko tinggi (BR, ID, CD, PE, CO, BO, VE, MY)

Ambang batas dimuat dari file konfigurasi, bukan di-hardcode, sehingga dapat disesuaikan tanpa mengubah kode. Titik masuk utamanya adalah:

async def analyze_plot(
    geometry_data,     # geometri GeoJSON
    plot_id,           # ID database
    check_alerts=True,# apakah akan mengkueri GLAD + RADD
    country_code=None # kode negara ISO untuk penilaian risiko
):
        

Poin penting: Analyzer tidak mengambil datanya sendiri. Ia mendelegasikan ke layanan GLAD dan RADD, lalu menggabungkan jawaban mereka. Ini adalah orkestrator, bukan lapisan data.

Langkah 4

Layanan Alert

Sistem memiliki dua layanan alert yang bekerja secara independen tetapi menghasilkan hasil yang kompatibel:

GLAD (glad_alert_service.py, 35KB) — Menggunakan dataset Hansen Global Forest Change melalui Google Earth Engine. Resolusi: 30m. Cakupan: global, sejak 2001. Ini berbasis optik (Landsat), yang berarti awan dapat menghalangi deteksi.

RADD (radd_alert_service.py) — Menggunakan citra radar Sentinel-1 melalui Google Earth Engine. Resolusi: 10m. Cakupan: wilayah tropis, sejak 2019. Karena menggunakan radar, ia dapat bekerja menembus awan dan di malam hari.

Kedua layanan mengkueri GEE dan mengembalikan bentuk data yang sama:

{
    "has_alerts": True,
    "alert_count": 12,
    "total_area_ha": 3.45,
    "loss_by_year": { "2021": 1.2, "2022": 2.25 }
}
        

Mengapa dua sistem? GLAD memiliki rekam jejak lebih panjang dan cakupan global. RADD dapat melihat menembus awan. Ketika keduanya mendeteksi deforestasi pada plot yang sama, tingkat kepercayaan paling tinggi. Analyzer melakukan validasi silang terhadap keduanya.

Langkah 5

Report Generator

report_generator.py (76KB) adalah file terbesar di seluruh codebase. File ini menggunakan ReportLab untuk membangun laporan PDF multi-halaman yang berfungsi sebagai dokumen kepatuhan utama.

Satu laporan mencakup:

Ringkasan kepatuhan — keputusan, tingkat risiko, metrik utama
Citra satelit — tiga periode waktu (baseline 2018, periode alert, saat ini)
Peta NDVI — perubahan kesehatan vegetasi dari waktu ke waktu
Tabel perbandingan GLAD/RADD — analisis alert berdampingan
Klasifikasi tutupan lahan — rincian ESA WorldCover

Mengapa 76KB? Pembuatan PDF secara inheren membutuhkan banyak kode. Setiap halaman memerlukan perhitungan koordinat yang presisi, definisi warna, ukuran font, dan logika tata letak. File ini besar karena melakukan banyak pekerjaan visual, bukan karena terorganisir dengan buruk.

Bekerja dengan Komponen

Cara menemukan di mana sebuah fitur diimplementasikan

Codebase mengikuti konvensi folder yang konsisten. Mengetahui konvensi ini membawa Anda ke file yang tepat dalam hitungan detik.

Untuk logika bisnis (pekerjaan sesungguhnya), lihat di backend/services/. Di sinilah analisis, alert, laporan, dan email diimplementasikan.
Untuk endpoint HTTP (URL apa yang ada, parameter apa yang diterima), lihat di backend/api/. Setiap file di sini adalah router yang memanggil layanan.
Untuk bentuk data (field apa yang dimiliki objek), lihat di backend/models/. Anda akan menemukan PlotData, AnalysisResult, ComplianceStatus, dan lainnya di sini.
Untuk integrasi sumber data eksternal (GEE, Planetary Computer, CDSE), lihat di backend/providers/. Setiap provider mengimplementasikan antarmuka yang sama.
Untuk infrastruktur (koneksi database, konfigurasi), lihat di backend/utils/.

Cara menambahkan endpoint API baru

Buat fungsi endpoint Anda di file yang sesuai di dalam backend/api/. Jika endpoint Anda berkaitan dengan analisis, tambahkan ke api/analysis.py. Jika itu domain baru, buat file baru.
Tambahkan decorator untuk mendaftarkan rute: @router.get("/your-path") atau @router.post("/your-path").
Jika Anda membuat file baru, impor routernya di app.py dan daftarkan dengan app.include_router(your_router, prefix="/api/your-domain").
Jika Anda menggunakan file yang sudah ada, router sudah terdaftar — endpoint baru Anda langsung tersedia.

Cara menelusuri bug melalui lapisan-lapisan

Mulai dari lapisan API. Temukan endpoint di backend/api/ yang menangani request yang gagal. Periksa parameter apa yang diterima dan fungsi layanan apa yang dipanggil.
Ikuti ke layanan. Buka fungsi layanan di backend/services/. Baca logikanya. Periksa data apa yang diharapkan dan apa yang dikembalikan.
Periksa model data. Buka kelas yang relevan di backend/models/. Verifikasi bahwa nama field dan tipe cocok dengan apa yang dihasilkan layanan dan apa yang dikembalikan API.
Periksa kueri database. Jika bug melibatkan data tersimpan, lihat SQL di backend/utils/database.py atau kueri inline di layanan. Verifikasi nama kolom cocok dengan model.
Tambahkan logging di setiap lapisan. Modul logging Python sudah diimpor di sebagian besar file. Tambahkan panggilan logger.info() di setiap batas untuk melihat di mana data berubah bentuk secara tidak terduga.

Mengapa Struktur Ini?

Pemisahan Tanggung Jawab

Codebase menggunakan arsitektur berlapis dengan empat lapisan berbeda:

Lapisan API

Penanganan HTTP. Menerima request, memvalidasi input, memanggil layanan, memformat response. Berada di backend/api/.

Lapisan Layanan

Logika bisnis. Melakukan pekerjaan sesungguhnya — menganalisis hutan, menghasilkan alert, membuat PDF. Berada di backend/services/.

Lapisan Model

Bentuk data. Mendefinisikan seperti apa plot, hasil analisis, atau alert. Berada di backend/models/.

Lapisan Database

Penyimpanan. Koneksi PostGIS, pengaturan skema, kueri. Berada di backend/utils/.

Bayangkan seperti rumah sakit. Meja resepsionis (lapisan API) tidak melakukan operasi — ia memeriksa janji temu Anda dan mengarahkan Anda ke departemen yang tepat. Tim bedah (lapisan layanan) melakukan pekerjaan sesungguhnya, menggunakan rekam medis standar (model) dan ruang arsip (database). Setiap departemen memiliki tanggung jawab yang jelas, dan mencampurnya akan menciptakan kekacauan.

Pemisahan ini berarti Anda dapat mengubah tampilan PDF tanpa menyentuh endpoint API. Anda dapat mengganti database tanpa menulis ulang logika bisnis. Setiap lapisan memiliki satu tugas, dan menjalankan tugas itu dengan baik.

Lapisan Layanan Adalah Tempat Beban Utama

Jika Anda melihat ukuran file, polanya jelas:

File	Ukuran	Tujuan
`report_generator.py`	76KB	Pembuatan PDF dengan citra satelit, NDVI, tutupan lahan
`forest_analyzer_with_alerts.py`	45KB	Mesin kepatuhan inti
`glad_alert_service.py`	35KB	Deteksi deforestasi optik via GEE
`analysis_queue_worker.py`	28KB	Pemrosesan job latar belakang

File-file layanan ini adalah produknya. Lapisan API hanyalah pembungkus tipis — sebagian besar fungsi endpoint kurang dari 30 baris. Fungsi-fungsi tersebut memvalidasi input, memanggil metode layanan, dan mengembalikan hasilnya. Semua pengetahuan domain, semua aturan tentang apa yang merupakan deforestasi, semua logika untuk menggabungkan data GLAD dan RADD — semuanya ada di layanan.

Ini disengaja. Jika Anda memindahkan logika bisnis ke lapisan API, Anda tidak dapat menggunakannya kembali dari worker antrian latar belakang. Dengan menyimpannya di layanan, baik API sinkron maupun antrian async dapat memanggil metode analyze_plot() yang sama.

Mengapa 13 Router?

Setiap router menangani satu domain: analisis, autentikasi, laporan, alert, manajemen antrian, pemasok, plot, organisasi, metrik, rantai pasok, pemrosesan batch, dasbor, dan analisis lanjutan (dengan WebSocket).

Ini adalah praktik standar FastAPI. Menempatkan semua endpoint dalam satu file akan menciptakan file raksasa 3000 baris yang mustahil dinavigasi. Router terpisah berarti:

Setiap file terfokus dan mudah dibaca (biasanya 100-300 baris)
Developer berbeda dapat mengerjakan domain berbeda tanpa konflik merge
Pengujian dapat menargetkan satu router pada satu waktu
Prefix URL bersifat eksplisit: /api/analysis, /api/auth, /api/alerts

Direktori Komponen

File Utama

File	Peran	Ukuran	Metode Utama
`app.py`	Titik masuk	~300 baris	`startup_event()`
`forest_analyzer_with_alerts.py`	Mesin analisis inti	45KB	`analyze_plot()`
`glad_alert_service.py`	Deteksi deforestasi optik	35KB	`get_alerts_for_geometry_gee()`
`radd_alert_service.py`	Deteksi deforestasi radar	—	`get_alerts_for_geometry()`
`report_generator.py`	Pembuatan PDF	76KB	`generate_compliance_report()`
`analysis_queue_worker.py`	Pemroses job latar belakang	28KB	`_worker_loop()`
`email_service.py`	Notifikasi	—	`send_analysis_complete_email()`
`file_processor_simple.py`	Penguraian unggahan	—	`process_file()`

Struktur Folder

Folder	Tujuan
`backend/api/`	Endpoint HTTP
`backend/services/`	Logika bisnis
`backend/models/`	Kelas data
`backend/providers/`	Adapter sumber data eksternal
`backend/utils/`	Infrastruktur (DB, konfigurasi)
`frontend/public/`	Antarmuka browser (HTML, JS)

Pohon File

backend/ Root aplikasi server

app.py Titik masuk, pendaftaran router, startup

api/ Endpoint HTTP (13 router)

analysis.py Unggah dan analisis

auth.py Login, registrasi, token

reports.py Pembuatan PDF/Excel

alerts.py GLAD, RADD, gabungan

queue.py Manajemen job async

dashboard.py Ringkasan analitik

batch.py Pemrosesan batch

suppliers.py CRUD pemasok

plots.py CRUD plot

organizations.py CRUD organisasi

metrics.py Endpoint Prometheus

supply_chain.py Hubungan pemasok

services/ Logika bisnis (pekerjaan berat)

forest_analyzer_with_alerts.py Mesin kepatuhan inti (45KB)

glad_alert_service.py Alert optik via GEE (35KB)

radd_alert_service.py Alert radar via GEE

report_generator.py Laporan PDF (76KB)

analysis_queue_worker.py Antrian latar belakang (28KB)

file_processor_simple.py Validasi unggahan

email_service.py Notifikasi SMTP

sentinel_imagery_service.py Citra satelit + NDVI

land_cover_service.py ESA WorldCover

biodiversity_service.py KBA/EBA/IBA/GBIF

alert_scheduler.py Pemeriksaan alert berkala

stuck_analysis_fixer.py Auto-retry job terhenti

models/ Kelas data

__init__.py PlotData, AnalysisResult, ComplianceStatus

alerts.py DeforestationAlert, AlertSubscription

user.py Model User dengan tier langganan

queue.py AnalysisQueueItem, QueueStatus

providers/ Adapter sumber data eksternal

base.py Antarmuka abstrak

factory.py Factory provider

gee_provider.py Google Earth Engine

planetary_provider.py Microsoft Planetary Computer

cdse_provider.py Copernicus Data Space

utils/ Infrastruktur

database.py Koneksi PostgreSQL + PostGIS

routes/ Rute dengan WebSocket

enhanced_analysis.py Analisis batch dengan progres real-time

frontend/public/ Antarmuka browser

index.html Halaman aplikasi utama

admin.html Dasbor admin

dashboard.html Dasbor pengguna