file_table_reader/README.md

# 🛰️ FastAPI Backend — Sistem Referensi & Validasi Data Geospasial

Proyek ini adalah backend berbasis **FastAPI** yang menangani proses **pembacaan data spasial (Shapefile, GeoJSON)**, **ekstraksi PDF**, serta **validasi dan sinkronisasi data** terhadap referensi basis data menggunakan **PostgreSQL/PostGIS** dan **RapidFuzz** untuk pencocokan string.

---

## ⚙️ Fitur Utama

✅ Upload dan ekstrak file `.zip` berisi `.shp` atau `.gdb`  
✅ Parsing PDF menggunakan `pdfplumber`  
✅ Konversi dan validasi geometri (Shapely + GeoPandas)  
✅ Pencocokan fuzzy string terhadap referensi DB (`RapidFuzz`)  
✅ Integrasi PostgreSQL / PostGIS melalui SQLAlchemy  
✅ Middleware CORS untuk komunikasi dengan frontend  
✅ Dukungan konfigurasi `.env` (via `python-dotenv`)  

---

## 🧱 Struktur Proyek

```
project-root/
│
├── core/
│   ├── config.py              # Konfigurasi environment & DB URL
│   └── utils/                 # Fungsi tambahan (opsional)
│
├── routes/
│   └── upload_routes.py       # Endpoint untuk upload & validasi
│
├── services/
│   └── pdf_service.py         # Parser PDF
│   └── shapefile_service.py   # Pembaca dan validator shapefile
│
├── main.py                    # Entry point FastAPI
├── requirements.txt           # Daftar dependensi
├── .env                       # File konfigurasi (DB_URL, schema, dll)
└── README.md                  # Dokumentasi proyek ini
```

---

## 🔧 Instalasi dan Setup

### 1️⃣ Clone Repository
```bash
git clone https://git.labmu.ac.id/username/nama-proyek.git
cd nama-proyek
```

### 2️⃣ Buat Virtual Environment
```bash
python -m venv venv
source venv/bin/activate   # (Linux/Mac)
venv\Scripts\activate      # (Windows)
```

### 3️⃣ Instal Dependensi
```bash
pip install -r requirements.txt
```

### 4️⃣ Konfigurasi File `.env`
Buat file `.env` di root proyek:

```env
REFERENCE_DB_URL=postgresql+psycopg2://user:password@localhost:5432/nama_db
REFERENCE_SCHEMA=public
```

---

## 🚀 Menjalankan Server

Jalankan server FastAPI menggunakan **Uvicorn**:

```bash
uvicorn main:app --reload
```

Server akan berjalan di:  
👉 http://127.0.0.1:8000

---

## 🧠 Contoh Endpoint

| Method | Endpoint | Deskripsi |
|--------|-----------|-----------|
| `POST` | `/upload/shapefile` | Upload file `.zip` berisi `.shp` |
| `POST` | `/upload/pdf` | Ekstrak tabel dari file PDF |
| `GET`  | `/reference/check` | Validasi data terhadap referensi DB |

---

## 🧩 Teknologi yang Digunakan

| Kategori | Library |
|-----------|----------|
| Framework | FastAPI, Starlette |
| Database | SQLAlchemy, psycopg2, PostgreSQL/PostGIS |
| Data & Geo | Pandas, GeoPandas, Shapely, Fiona, PyProj |
| Parsing | pdfplumber |
| Matching | RapidFuzz |
| Utilitas | python-dotenv, pathlib, zipfile |
| Server | Uvicorn |

---

## 🧪 Testing

Jalankan server dan uji dengan **Swagger UI**:
```
http://127.0.0.1:8000/docs
```

Atau gunakan **cURL / Postman** untuk pengujian manual.

---

## 🧰 Tips Penggunaan

- Pastikan `GDAL`, `GEOS`, dan `PROJ` sudah terinstal di sistem jika menggunakan `GeoPandas` / `Fiona`.
- Gunakan `pip freeze > requirements.txt` untuk memperbarui dependensi.
- Gunakan `.gitignore` agar file sensitif seperti `.env` tidak ikut ter-push.

---

## 👨‍💻 Pengembang
**Nama:** Dimas Anhar  
**Lab / Organisasi:** [Nama Lab atau Institusi]  
**Email:** (opsional)  

---

## 📄 Lisensi
Proyek ini dikembangkan untuk keperluan penelitian dan pengembangan internal.  
Lisensi dapat disesuaikan sesuai kebijakan lab atau institusi.