# 1. Judul
**Desain Restrukturisasi PoC Task 2 Menuju FastAPI Backend Service**

# 2. Tanggal
4 Mei 2026

# 3. Deskripsi
Dokumen ini menguraikan rencana teknis untuk merestrukturisasi repositori *Proof of Concept* (PoC) Task 2 (Migrasi Neo4j Vector Knowledge Graph). Fokus utamanya adalah merapikan skrip-skrip Python yang saat ini berserakan di *root* direktori, dan menyusunnya kembali ke dalam hierarki arsitektur berstandar *FastAPI*. Perubahan ini bertujuan untuk mengubah PoC menjadi kerangka *backend service* yang bersih, mudah di- *maintenance*, dan siap diintegrasikan dengan *frontend* `mysre-monorepo`. Restrukturisasi ini tidak mengubah fungsionalitas inti, murni pengorganisasian kode.

# 4. Metodologi
Restrukturisasi ini mengadopsi pola *Separation of Concerns* (Pemisahan Tanggung Jawab) khas ekosistem *FastAPI*:
*   **Routing Layer (`app/api`)**: Khusus untuk menangani *endpoint* HTTP (REST API).
*   **Business Logic Layer (`app/services`)**: Tempat di mana seluruh logika orkestrasi AI, ekstraksi LLM, pemotongan (*chunking*), dan interaksi ke Neo4j berada.
*   **Maintenance Layer (`scripts/`)**: Untuk menampung skrip utilitas yang dijalankan secara manual lewat CLI (misalnya: manajemen indeks *database*).
*   **Archival Strategy**: Modul lawas (*legacy*) akan dikarantina untuk menjaga kebersihan *repository* utama.

# 5. Keputusan (Decision Log)
1.  **Transformasi menjadi Arsitektur Web Service (FastAPI)**: Karena PoC ini ditargetkan menjadi *backend service* bagi `mysre-monorepo`, struktur *FastAPI* dipilih untuk mempermudah integrasi HTTP *endpoint* ke depannya.
2.  **Pemisahan Layer API dan Layanan**: Mencegah penumpukan kode pada satu *file*. Fungsi-fungsi yang ada di `orchestrator_ingest.py` kelak akan dipisah dan ditempatkan ke dalam folder `app/services/`.
3.  **Karantina Skrip Standalone**: Skrip eksekusi seperti `setup_indexes.py`, `drop_indexes.py`, dll, diamankan ke folder `scripts/`. Penggunaan skrip ini murni untuk pemeliharaan *database* melalui terminal, bukan via HTTP.
4.  **Pengarsipan Modul Ekstraksi Hibrida V1**: Folder `poc-ekstraksi-hibrida` akan dipindahkan ke folder `archive/` karena merupakan versi lama yang sudah tidak aktif digunakan di alur utama (redesign_2).

# 6. Alur Diagram
```mermaid
flowchart TD
    classDef client fill:#f9f9f9,stroke:#0071C5,stroke-width:2px,color:#232F3E
    classDef api fill:#fff,stroke:#FF9900,stroke-width:2px,color:#232F3E
    classDef service fill:#eaffea,stroke:#1e8900,stroke-width:2px,color:#1e8900
    classDef script fill:#f4f4f4,stroke:#666,stroke-width:2px,color:#333
    classDef db fill:#f9f9f9,stroke:#9B59B6,stroke-width:2px,color:#232F3E,shape:cylinder

    Client["🌐 Frontend (mysre-monorepo)<br>atau API Client"]:::client
    CLI["🖥️ CLI / Terminal"]:::client
    
    subgraph FastAPI_Backend ["⚙️ FastAPI Application (app/)"]
        direction TB
        Main["app/main.py<br>(Entry Point)"]:::api
        Router["app/api/<br>(REST Endpoints)"]:::api
        
        subgraph Business_Services ["Business Logic (app/services/)"]
            IngestSvc["ingestion.py<br>(ex: orchestrator_ingest)"]:::service
            ParserSvc["parser/<br>(Smart Chunker & Hybrid)"]:::service
            GraphSvc["pagerank.py<br>(ex: calculate_pagerank)"]:::service
            StorageSvc["storage/<br>(Supabase Client)"]:::service
        end
    end

    subgraph Utilities ["🛠️ Standalone Scripts (scripts/)"]
        DBTools["setup_indexes.py<br>reset_edges.py<br>dll."]:::script
    end

    DB_Neo4j[("Neo4j AuraDB")]:::db
    DB_Supabase[("Supabase")]:::db

    Client -->|HTTP Request| Main
    Main --> Router
    Router --> IngestSvc
    Router --> GraphSvc
    
    IngestSvc --> ParserSvc
    IngestSvc --> StorageSvc
    
    Business_Services -.-> DB_Neo4j
    Business_Services -.-> DB_Supabase
    
    CLI -->|Execute| DBTools
    DBTools -.-> DB_Neo4j
```

# 7. Struktur Folder (Tree)
Target hierarki akhir *repository* setelah restrukturisasi:

```text
poc_neo4j_migrating-chunking-integrated-gh-(Restruct)/
├── app/
│   ├── __init__.py
│   ├── main.py                    # Entry point aplikasi FastAPI
│   ├── api/                       # (Disiapkan untuk endpoint router nantinya)
│   │   ├── __init__.py
│   │   └── routes/
│   ├── core/                      # (Untuk konfigurasi, env, dsb di masa depan)
│   │   └── __init__.py
│   └── services/                  # Lokasi logika inti (sebelumnya di root)
│       ├── __init__.py
│       ├── ingestion.py           # Ganti nama dari orchestrator_ingest.py
│       ├── pagerank.py            # Ganti nama dari calculate_pagerank.py
│       ├── parser/                # Pindahan dari core/parser/
│       │   ├── hybrid_parser.py
│       │   └── smart_chunker.py
│       └── storage/               # Pindahan dari core/storage/
│           └── supabase_client.py
├── scripts/                       # Pindahan script utilitas dari root
│   ├── drop_indexes.py
│   ├── edge_reasoning_quality_gate_check.py
│   ├── embed_and_ingest.py
│   ├── query_similarity.py
│   ├── rebuild_edges_existing_nodes.py
│   ├── regression_corpus_check.py
│   ├── reset_similarity_edges.py
│   ├── setup_indexes.py
│   ├── test_performance.py
│   └── test_scilit_parsing.py
├── archive/                       # Pindahan dari poc-ekstraksi-hibrida
├── tests/                         # (Folder untuk unit testing di masa depan)
├── Literature/                    # Folder sumber PDF
├── Markdown/                      # Dokumentasi & Plan
├── requirements.txt
├── schema.prisma
├── prisma.config.ts
└── .env
```

# 8. Asumsi
1.  Skrip-skrip yang dipindahkan masih memiliki kapabilitas logika yang berjalan dengan baik; fokus *task* hanya pada perpindahan lokasi *file* dan penyesuaian jalur import (`import path`).
2.  Skema *database* Supabase (`schema.prisma`) dan referensi *environment* (`.env`) tetap berada di *root*.
3.  Pembuatan kerangka asli FastAPI (`app/main.py` dan `app/api`) akan dibuat sebagai draf/ *skeleton* kosong atau minimalis untuk memvalidasi *import* dapat berjalan.

# 9. Langkah Implementasi
1.  **Persiapan Struktur Dasar**: Membuat *folder* `app/`, `app/api/`, `app/core/`, `app/services/`, `scripts/`, `tests/`, dan `archive/`. Menyertakan *file* `__init__.py` di setiap sub-direktori `app` agar dikenali sebagai modul Python.
2.  **Karantina Kode Legacy**: Memindahkan folder `poc-ekstraksi-hibrida` ke dalam `archive/`.
3.  **Isolasi Skrip Utilitas**: Memindahkan semua skrip *maintenance* dan alat *testing* (seperti `setup_indexes.py`, `query_similarity.py`, dll.) ke dalam folder `scripts/`.
4.  **Migrasi Logika Layanan (Services)**:
    *   Memindahkan folder `core/parser` dan `core/storage` ke dalam `app/services/`.
    *   Memindahkan dan mengganti nama `orchestrator_ingest.py` menjadi `app/services/ingestion.py`.
    *   Memindahkan dan mengganti nama `calculate_pagerank.py` menjadi `app/services/pagerank.py`.
5.  **Perbaikan Jalur Import (Fix Imports)**: Memperbarui semua sintaks `import` di seluruh file yang dipindahkan (misalnya, `from core.parser...` menjadi `from app.services.parser...`).
6.  **Uji Coba Validasi (Sanity Check)**: Memastikan skrip yang dipindahkan dapat dieksekusi tanpa *error* `ModuleNotFoundError`.

# 10. Tabel Eksekusi Task

| Check Box | Fase | Task | Detail Task | Deskripsi | Acceptance Criteria |
| :---: | :---: | :---: | :--- | :--- | :--- |
| [x] | 1 | Preparation | **Buat Direktori Baru** | Buat struktur folder FastAPI (`app/`, `app/api/`, `app/services/`, `scripts/`, `archive/`, `tests/`) dengan file `__init__.py` yang sesuai. | Folder-folder terbentuk dan Python mengenali struktur `app` sebagai *package* valid. |
| [x] | 1 | Archive | **Karantina Legacy** | Pindahkan `poc-ekstraksi-hibrida` secara utuh ke `archive/`. Hapus sisa folder kosong jika ada. | Folder `poc-ekstraksi-hibrida` tidak ada lagi di *root*. |
| [x] | 2 | Migration | **Pindahkan Skrip CLI** | Pindahkan ke `scripts/`: `setup_indexes.py`, `drop_indexes.py`, `rebuild_edges_existing_nodes.py`, `reset_similarity_edges.py`, `query_similarity.py`, skrip uji (performa/scilit/regression), dan `embed_and_ingest.py`. | Semua file tersebut sukses dipindahkan ke `scripts/`. |
| [x] | 2 | Migration | **Pindahkan Layanan Inti** | Pindahkan folder `core/parser` dan `core/storage` ke `app/services/`. Pindahkan dan *rename* `orchestrator_ingest.py` -> `app/services/ingestion.py`, serta `calculate_pagerank.py` -> `app/services/pagerank.py`. Hapus sisa folder `core/`. | Modul *parser*, *storage*, *ingestion*, dan *pagerank* rapi di dalam `app/services/`. |
| [x] | 3 | Refactor | **Perbaiki Jalur Import** | Buka seluruh file yang terdampak dan sesuaikan jalur import (contoh: ubah `from core.parser` menjadi `from app.services.parser`). | Kode tidak mengalami bentrokan jalur import (*clean import path*). |
| [x] | 3 | Refactor | **Fix Pathing di Scripts** | Sesuaikan kembali jalur referensi lokal pada skrip utilitas yang memanggil *services* atau membaca path seperti `Literature/` akibat perubahan letak folder. | Skrip dapat membaca *path* ke file sumber/referensi dengan akurat dari lokasi baru. |
| [x] | 4 | Validation | **Uji Eksekusi (Dry-Run)** | Lakukan eksekusi percobaan terhadap salah satu skrip di `scripts/` atau pemanggilan modul *services* untuk memastikan tidak ada import yang rusak. | Perintah eksekusi tidak memicu *traceback* `ModuleNotFoundError`. |