# Plan & Arsitektur — OCR Service Surat Sprint Kepolisian

## 1. Penilaian Jujur Tech Stack yang Diusulkan

Tech stack Anda (FastAPI + PaddleOCR + OpenCV/Pillow + Regex) **sudah bagus dan layak produksi**, tapi **belum tentu paling optimal akurasinya** untuk kasus surat sprint. Ada beberapa gap yang perlu diisi sebelum bisa disebut "terbaik".

### Yang sudah tepat
| Komponen | Alasan |
|---|---|
| **FastAPI** | Async native, Pydantic validation, OpenAPI docs otomatis, ideal untuk ML serving. |
| **PaddleOCR (PP-OCRv4/v5)** | Salah satu OCR open-source terbaik untuk dokumen campuran teks + tabel, mendukung Latin (cocok untuk Bahasa Indonesia), bisa jalan on-premise (penting untuk dokumen kepolisian yang sensitif — **cloud OCR seperti Google Vision/AWS Textract sebaiknya dihindari** karena masalah kerahasiaan). |
| **OpenCV + Pillow** | Standar industri untuk preprocessing. |
| **Regex/rule-based** | Cocok untuk dokumen terstruktur seperti sprint yang format-nya relatif baku. |

### Yang masih kurang / perlu ditambah

1. **Table extraction belum tertangani**
   Daftar personel di surat sprint hampir selalu berbentuk **tabel** (No, Pangkat, NRP, Nama, Jabatan, Keterangan). Regex pada teks linear dari OCR biasa **akan kacau** ketika baris tabel pecah atau kolom bergeser. Solusi: gunakan **PaddleOCR PP-Structure** (modul table recognition bawaan Paddle) atau model khusus seperti **TableTransformer (Microsoft)**.

2. **Document detection & dewarping untuk foto HP belum eksplisit**
   Foto HP bermasalah karena: perspektif miring, lipatan, bayangan, lighting tidak rata, fokus tidak merata. OpenCV crop + perspective transform manual saja sering gagal. Tambahkan:
   - **Document corner detection**: `DocTR` / `MobileSAM` / model edge-based, atau heuristik kontur OpenCV sebagai fallback.
   - **Dewarping**: `DocTr` / `DewarpNet` untuk halaman yang melengkung (lipatan).
   - **Shadow removal**: algoritma background division atau model spesialis.

3. **Strategi ekstraksi 100% regex itu rapuh**
   Surat sprint dari satuan berbeda (Polda, Polres, Polsek, Mabes) punya **variasi format**: header berbeda, urutan field berbeda, kadang pangkat disingkat (`AKP`, `IPDA`) kadang ditulis penuh. Regex murni akan butuh ratusan rule dan tetap miss kasus baru.
   **Rekomendasi pendekatan hybrid**:
   - **Layer 1 — Regex/rule** untuk field deterministik (Nomor sprint, tanggal, dasar hukum) yang format-nya baku.
   - **Layer 2 — Schema-aware extraction** menggunakan **LLM lokal** (Llama 3.1 8B / Qwen2.5 7B via Ollama atau vLLM) dengan structured output (JSON schema / Pydantic) untuk field yang variatif (jabatan, keterangan tugas).
   - **Layer 3 — Validation** terhadap master data (daftar pangkat valid, format NRP 8 digit, dll).

4. **Tidak ada confidence scoring & human-in-the-loop**
   Untuk dokumen kepolisian, **akurasi 100% otomatis itu mitos**. Sistem harus:
   - Mengeluarkan confidence score per field.
   - Otomatis flag dokumen low-confidence untuk review manusia.
   - Sediakan UI/endpoint koreksi yang feedback-nya bisa dipakai retraining.

5. **Alternatif end-to-end yang patut dipertimbangkan**
   Jika nanti volume dokumen besar dan format relatif stabil, fine-tuning model **Document Understanding** end-to-end bisa lebih akurat:
   - **Donut** (OCR-free, langsung image → JSON).
   - **LayoutLMv3** (kombinasi teks + layout + visual).
   - **Surya OCR** (newer, sangat bagus untuk dokumen).
   Untuk MVP, tetap pakai PaddleOCR. Donut/LayoutLM adalah opsi V2 setelah ada labeled dataset cukup (~500–1000 dokumen).

### Verdict
Stack Anda **bisa mencapai ~85–92% akurasi field-level** untuk surat sprint dengan kualitas scan baik, dan **~70–80%** untuk foto HP, **kalau ditambah** komponen di atas. Tanpa table extraction + dewarping + hybrid extraction, akurasinya akan jatuh di kondisi nyata.

---

## 2. Arsitektur yang Direkomendasikan

### 2.1 Diagram Logis

```
┌────────────────────────────────────────────────────────────────────┐
│                         Client (Web/Mobile)                        │
└──────────────────────────────┬─────────────────────────────────────┘
                               │ HTTPS (multipart upload)
                               ▼
┌────────────────────────────────────────────────────────────────────┐
│                    FastAPI Gateway (stateless)                     │
│   - Auth (JWT/API key)   - Rate limit   - Request validation       │
└──────────────────────────────┬─────────────────────────────────────┘
                               │ enqueue job
                               ▼
┌────────────────────────────────────────────────────────────────────┐
│              Job Queue (Redis + Celery / RQ / Dramatiq)            │
└──────────────────────────────┬─────────────────────────────────────┘
                               ▼
┌────────────────────────────────────────────────────────────────────┐
│                    OCR Worker Pipeline (GPU/CPU)                   │
│  ┌────────────┐  ┌──────────────┐  ┌───────────┐  ┌────────────┐   │
│  │ 1. Ingest  │→ │ 2. Preproc   │→ │ 3. OCR +  │→ │ 4. Extract │   │
│  │  & detect  │  │ (deskew,     │  │  Layout   │  │ (regex +   │   │
│  │  PDF/IMG   │  │  dewarp,     │  │  PP-Struct│  │  LLM +     │   │
│  │            │  │  denoise)    │  │  + Table) │  │  validate) │   │
│  └────────────┘  └──────────────┘  └───────────┘  └─────┬──────┘   │
│                                                         │          │
│                          ┌──────────────────────────────┘          │
│                          ▼                                         │
│                   ┌─────────────┐                                  │
│                   │ 5. Confidence│ → low conf? flag for review    │
│                   │   scoring    │                                 │
│                   └──────┬───────┘                                 │
└──────────────────────────┼─────────────────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────────────────┐
│           Storage: PostgreSQL (metadata) + MinIO/S3 (file)         │
│           + Vector store opsional (untuk dedup / search)           │
└────────────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────────────────┐
│           Review UI (optional) — koreksi manual + audit trail      │
└────────────────────────────────────────────────────────────────────┘
```

### 2.2 Pipeline Detail per Tahap

**Tahap 1 — Ingest & Document Detection**
- PDF: render setiap halaman jadi image @ 300 DPI (`pdf2image` / `PyMuPDF`).
- Image (foto HP): deteksi sudut dokumen → crop → perspective transform.
  - Library: OpenCV `findContours` (cepat) sebagai fallback, **DocTR document detector** (lebih akurat) sebagai utama.

**Tahap 2 — Preprocessing**
- Deskew (rotation correction) — Hough transform atau model.
- Dewarp (untuk foto buku/lipatan) — `DewarpNet` atau model RNN.
- Adaptive thresholding (untuk foto dengan lighting tidak rata).
- Shadow removal (background division).
- Denoise (Non-Local Means).
- Resize ke ukuran optimal OCR (~1500–2500 px sisi panjang).

**Tahap 3 — OCR + Layout Analysis**
- **PaddleOCR PP-Structure** dijalankan sekali → menghasilkan:
  - Bounding boxes + teks + confidence per word/line.
  - Table region detection + table-to-HTML/JSON.
  - Layout type per region (title, paragraph, table, figure).
- Output ditampung sebagai struktur intermediate (mirip hOCR / ALTO XML).

**Tahap 4 — Information Extraction**
- **4a. Header parsing (regex)**: Nomor sprint, tanggal, satuan penerbit, dasar hukum, perihal. Format relatif baku → regex sangat cocok.
- **4b. Personnel table extraction**: ambil dari hasil PP-Structure table → mapping kolom (Pangkat, NRP, Nama, Jabatan, Keterangan).
- **4c. LLM fallback**: untuk field yang regex/table miss, kirim chunk teks + JSON schema ke LLM lokal (Ollama / vLLM) dengan **structured output** (Pydantic via `outlines` / `instructor`).
- **4d. Validation layer**:
  - NRP: 8 digit numerik.
  - Pangkat: harus ada di daftar master pangkat Polri.
  - Tanggal: parse + sanity check.
  - Cross-check: jumlah personel di body = jumlah baris tabel.

**Tahap 5 — Confidence Scoring & Routing**
- Aggregate confidence: weighted average dari OCR confidence + validation pass/fail + LLM logprob (kalau pakai).
- Threshold (mis. < 0.85) → status `NEEDS_REVIEW`.
- Threshold tinggi (≥ 0.95) + semua validasi pass → status `AUTO_APPROVED`.

### 2.3 API Endpoint (FastAPI)

```
POST   /api/v1/documents              # upload, kembalikan job_id
GET    /api/v1/documents/{job_id}     # poll status + hasil
GET    /api/v1/documents/{job_id}/raw # raw OCR output (debug)
PATCH  /api/v1/documents/{job_id}     # koreksi manual (HITL)
GET    /api/v1/health                 # liveness
GET    /api/v1/metrics                # Prometheus
```

Response shape (contoh):
```json
{
  "job_id": "uuid",
  "status": "completed | processing | needs_review | failed",
  "confidence": 0.92,
  "data": {
    "nomor_sprint": "Sprin/123/IV/2025",
    "tanggal": "2025-04-21",
    "satuan_penerbit": "Polres Bandung",
    "dasar": ["...", "..."],
    "perihal": "...",
    "personel": [
      {"no": 1, "pangkat": "AKP", "nrp": "12345678", "nama": "...", "jabatan": "Kasat Reskrim", "confidence": 0.97},
      ...
    ],
    "ttd": {"pejabat": "...", "pangkat": "...", "nrp": "..."}
  },
  "review_flags": []
}
```

### 2.4 Tech Stack Final yang Direkomendasikan

| Layer | Pilihan | Catatan |
|---|---|---|
| API | **FastAPI** + Uvicorn/Gunicorn | sesuai usulan |
| Validation | **Pydantic v2** | wajib |
| Queue | **Redis + Celery** atau **Dramatiq** | OCR berat, jangan blocking request |
| OCR | **PaddleOCR PP-OCRv4 + PP-Structure** | tambah PP-Structure untuk tabel |
| Preprocessing | **OpenCV + Pillow** + **DocTR** (detection) | DocTR untuk foto HP |
| Extraction | **Regex + Ollama (Llama 3.1 8B / Qwen2.5 7B)** + **instructor/outlines** | hybrid |
| Storage | **PostgreSQL** (metadata) + **MinIO** (file blob) | self-hosted, sesuai compliance |
| Observability | **Prometheus + Grafana + Loki** | wajib produksi |
| Container | **Docker + docker-compose** (dev) → **Kubernetes** (prod) | |
| GPU | NVIDIA T4/A10 (1× cukup untuk MVP) | PaddleOCR jauh lebih cepat di GPU |

---

## 3. Roadmap Pengembangan (Bertahap)

### Fase 0 — Persiapan (1 minggu)
- Kumpulkan **dataset sampel**: minimal 50 surat sprint (campur PDF scan + foto HP) dari beragam satuan.
- Buat **ground truth labelling** untuk 20 dokumen (untuk evaluasi).
- Definisikan **schema output final** (JSON) bersama stakeholder.

### Fase 1 — MVP Pipeline Sinkron (2 minggu)
- Setup FastAPI skeleton + Pydantic schemas.
- Integrasi PaddleOCR PP-OCRv4 (CPU dulu, GPU menyusul).
- Preprocessing dasar: deskew + denoise + resize.
- Regex extraction untuk field header.
- Endpoint sinkron `POST /documents` (untuk dev/testing saja).
- **Evaluasi akurasi** terhadap 20 ground truth.

### Fase 2 — Robustness untuk Foto HP (2 minggu)
- Integrasi document detection (DocTR atau OpenCV contour).
- Perspective transform + dewarping.
- Shadow removal.
- Re-evaluasi akurasi pada subset foto HP.

### Fase 3 — Table Extraction (1.5 minggu)
- Integrasi PP-Structure untuk personnel table.
- Mapping kolom + validation (NRP, pangkat).
- Master data tabel pangkat Polri.

### Fase 4 — Async + Production Ready (1.5 minggu)
- Pindahkan ke arsitektur async dengan Celery + Redis.
- Storage MinIO + PostgreSQL.
- Auth, rate limit, logging, metrics.
- Docker compose untuk deployment.

### Fase 5 — LLM Hybrid Extraction (2 minggu)
- Setup Ollama / vLLM dengan model lokal.
- Structured output via `instructor`.
- Confidence scoring + routing ke review.

### Fase 6 — HITL Review UI (opsional, 2 minggu)
- Endpoint koreksi.
- Simple web UI (Next.js) untuk reviewer.
- Audit trail & feedback loop.

### Fase 7 — Optimasi Lanjutan (ongoing)
- Fine-tune PaddleOCR detection/recognition pada dataset internal.
- Eksplorasi Donut/LayoutLMv3 jika dataset sudah cukup.
- Batch processing & GPU optimization.

**Total estimasi MVP fungsional (Fase 1–4): ~7 minggu** dengan 1 backend engineer + 1 ML engineer.

---

## 4. Risiko & Mitigasi

| Risiko | Mitigasi |
|---|---|
| Data sensitif (kepolisian) bocor | Wajib on-prem; tidak ada cloud OCR; enkripsi at-rest (LUKS/pgcrypto) + in-transit (mTLS); audit log lengkap. |
| Variasi format antar satuan | Hybrid extraction (regex + LLM); kumpulkan sample dari banyak satuan sejak awal. |
| Foto HP kualitas buruk | Validasi kualitas image di client (resolusi minimal, blur detection) sebelum upload. |
| Akurasi tidak sampai target | HITL review wajib untuk dokumen low-confidence; jangan deploy fully-automatic. |
| Tanggung jawab hukum atas hasil OCR | Selalu simpan original document + flag bahwa hasil ekstraksi adalah "draft, perlu verifikasi manusia". |

---

## 5. Pertanyaan Sebelum Implementasi

Sebelum saya lanjut ke implementasi, mohon konfirmasi:

1. **Volume**: berapa dokumen/hari yang ditargetkan? (mempengaruhi pilihan async vs sync, GPU vs CPU)
2. **Deployment target**: on-prem mutlak, atau private cloud (GovCloud) boleh?
3. **Source dokumen**: apakah ada akses ke 20–50 sample surat sprint untuk dijadikan dataset awal?
4. **Integrasi**: service ini akan dipanggil sistem apa? (mempengaruhi auth & API contract)
5. **HITL**: apakah ada SDM untuk review manual dokumen low-confidence?
6. **Hardware**: sudah ada server GPU, atau perlu sizing rekomendasi?
7. **Format output final**: ada schema yang sudah dipakai sistem downstream?