Chirei Scraper - User Documentation

Memulai Pengenalan

Apa itu Chirei?

Chirei adalah web scraper yang dikonfigurasi secara visual dan dirancang untuk mempermudah alur ekstraksi multi-langkah (Listings, Detail Pages, Fanouts). Dibangun dengan FastAPI, Celery, Redis, dan PostgreSQL, Chirei sangat skalabel dan cocok untuk lingkungan staging maupun produksi.

Fitur Utama:

Visual Pipeline Builder: Canvas UI berbasis node-link graph untuk mendesain aliran data scraping secara drag-and-drop.
Visual Element Picker: Seleksi elemen klik-untuk-pilih langsung dari proxy iframe web tujuan dengan CSS selector otomatis.
API Interception: Menangkap XHR/fetch API calls secara otomatis, inspeksi JSON response, serta auto-detect array path dan field mapping.
Branching Pipeline: Multi-step scraping dengan dukungan Fan-out dan Named Link fields untuk ekstraksi paralel ke halaman turunan.
Skalabilitas Celery: Mengeksekusi jutaan node link di background secara terdistribusi dengan task queue dan retry mechanism.
Dukungan Tor Node Proxy: Me-routing endpoint .onion untuk Dark Web scraping secara otomatis via socks5h://127.0.0.1:9050.
Monitoring Dashboard: Real-time log streaming via WebSocket, memory/CPU tracking, dan history audit per task.
Chrome Extension: Sinkronisasi cookie otentikasi dari browser untuk scraping situs yang memerlukan login (Twitter/X, LinkedIn).

Arsitektur Sistem

Chirei menggunakan arsitektur modular yang terdiri dari beberapa komponen utama:

FastAPI Backend

REST API server + WebSocket endpoints untuk proxy, konfigurasi, eksekusi, dan monitoring real-time.

Canvas Pipeline Editor

HTML5 Canvas renderer dengan hit detection, undo/redo history, dan bezier curve edge routing.

Celery Task Queue

Distributed task execution dengan prefetch control, auto-retry, dan resource monitoring per worker.

PostgreSQL + MongoDB

PostgreSQL untuk konfigurasi dan history. MongoDB untuk penyimpanan hasil scrape berskala besar.

Memulai Dashboard

CHIREI SYSTEM DASHBOARD

Live Monitoring

Ada success rate, memory & cpu usage, dan statistik lainnya.

Memulai Membuat Config & Konfigurasi Node

Langkah-langkah Eksekusi

1

Membuat config atau palet baru.

Tekan tombol "New Config" pada bagian kiri panel.

2

Menambahkan Alamat Utama

Tentukan URL root/basis yang ingin diekstraksi dari target list anda pada panel bagian atas.

Kemudian beri nama config dan klik save.

3

Mapping Antar Node dan Page

Sambungkan (Drag & Drop Garis) Node satu ke node lainnya untuk pindah ke halaman berikutnya.

4

Konfigurasi Pagination

Pilih jenis pagination: selector (klik tombol Next), param (query parameter ?page=N), atau continuous (auto-stop saat data habis). Tentukan max_pages untuk membatasi halaman yang ditelusuri.

Tipe Node

Pipeline mendukung tiga jenis node yang dapat dikombinasikan:

Listing Node

Mengekstrak daftar item dari halaman berulang (list/grid). Secara otomatis mendeteksi container row dan link elements.

Detail Node

Mengekstrak konten spesifik dari halaman detail (artikel, profil). Dipanggil per-URL dari Listing node.

Fan-out Node

Membuat cabang pipeline parallel. Mendukung Named Link fields (_link:nama) untuk routing ke beberapa Detail nodes sekaligus.

Field Types

Setiap node memiliki fields yang bisa dikonfigurasi:

Type	Deskripsi	Selector Key
`text`	Mengambil konten teks dari elemen. Mendukung `::own-text` untuk direct text only.	`field_name`
`link`	Mengambil href dari anchor tag. Digunakan untuk navigasi ke halaman turunan.	`_link` atau `_link:nama`
`repeat`	Mengambil semua elemen yang cocok. Menghasilkan array values.	`_repeat:nama`

Fitur Visual Element Mapper

Alur Kerja Mapper

Mapper adalah mode utama untuk menentukan data apa yang akan diambil dari halaman web target. Berikut langkah-langkahnya:

1

Buka Tab Mapper

Klik tab Mapper di toolbar atas untuk masuk ke mode mapping. Panel di kanan akan menampilkan daftar Node Tabs dan daftar Fields untuk node yang aktif.

2

Load Halaman Target di preview

Masukkan URL target di field URL pada panel konfigurasi, lalu klik tommbol Load atau tekan tombol URL bar di toolbar mapper. Halaman akan dimuat di dalam preview. Server Chirei mem-proxy halaman tersebut agar bisa di-interaksi langsung dari dashboard.

Jika situs memerlukan login, isi field Cookies dengan cookie autentikasi (atau gunakan Chrome Extension Chirei untuk sync otomatis).

3

Buat Fields di Node

Klik tombol + Add Field di panel mapper untuk menambahkan field baru. Setiap field memiliki:

Nama: Label untuk kolom data (contoh: "Judul", "Harga", "Link Artikel").
Tipe: Pilih Text untuk mengambil teks, Link untuk mengambil href/URL, atau Repeat untuk mengambil semua elemen yang cocok sebagai array.
Selector: CSS selector yang akan diisi otomatis saat Anda klik elemen di preview.

4

Klik Pick lalu Klik Elemen di preview

Tekan tombol ⊕ Pick pada field yang ingin di-mapping. Status bar di bawah akan menampilkan nama field yang aktif. Lalu, klik elemen pada halaman di preview dan Chirei akan otomatis:

Menghasilkan CSS selector yang stabil untuk elemen tersebut.
Mengambil sample text/href dari elemen yang diklik.
Otomatis berpindah ke field berikutnya yang belum di-mapping.

5

Navigasi ke Node Berikutnya

Jika Anda memiliki field bertipe Link yang sudah di-mapping dan terhubung ke node lain via edge di Canvas, Chirei akan menawarkan untuk membuka URL tersebut di preview dan berpindah ke node target — sehingga Anda bisa langsung mapping field di halaman detail.

Fitur Panel Mapper

Node Tabs

Berpindah antar node pipeline di panel mapper. Badge hijau menunjukkan jumlah field yang sudah di-mapping per node.

Add Field

Tambahkan field baru ke node aktif. Field langsung masuk mode Pick agar bisa diklik di preview.

Tipe Field: Text / Link / Repeat

Text ambil innerText, Link ambil href (+ bisa buat cabang ke node lain), Repeat ambil semua elemen cocok sebagai array.

Pagination Selector

Klik ikon crosshair khusus untuk pagination. Klik tombol "Next Page" di halaman target untuk mengambil selectornya secara otomatis.

Mode Interaksi preview

Toolbar mapper memiliki dua mode untuk berinteraksi dengan halaman di preview:

Select Mode (Default)

Mode mapping. Hover menampilkan outline pada elemen, klik menangkap CSS selector dan sample data. Semua klik dicegah mengikuti link — fokus pada pemilihan elemen.

Interact Mode

Mode navigasi bebas. Klik berfungsi normal — bisa mengikuti link, scroll, expand accordion, mengisi form, dll. Berguna untuk menjelajahi halaman sebelum mapping.

Fitur API Interception

Cara Kerja

Ketika Anda membuka halaman target di Mapper, Chirei secara otomatis menginjeksikan interceptor JavaScript yang menangkap semua XHR dan fetch API calls:

1

Auto-Capture

Interceptor me-override window.fetch dan XMLHttpRequest. Setiap request JSON yang terdeteksi dikirim ke API panel via postMessage.

2

Smart Filtering

Request static assets (images, fonts, CSS, JS) dan tracking domains (Google Analytics, Facebook) otomatis di-skip. Hanya API calls yang relevan yang ditampilkan.

3

Proxy Routing

Request diproxy melalui /proxy-api endpoint untuk menghindari CORS restrictions. Cookie dan header otentikasi diforward via x-target-url dan x-target-cookies headers.

4

JSON Inspection

Klik pada API request untuk menginspeksi response. Sistem otomatis mendeteksi array candidates, best path, dan menghasilkan field mapping table.

Field Mapping & Pagination

Setelah inspeksi, Anda dapat mengkonfigurasi:

Fitur	Deskripsi
Auto-detect Array Path	Algoritma `find_array_candidates()` menelusuri seluruh JSON tree untuk menemukan array of objects terbesar.
Smart Flatten	Nested JSON di-flatten menjadi dot-notation keys (e.g., `user.profile.name`) untuk kemudahan mapping.
Field Type Detection	Key yang mengandung `url`, `link`, atau `href` otomatis ditandai sebagai type Link.
Pagination Types	Page Number (`?page=N`), Offset Param, dan Cursor/Token pagination — semuanya didukung.

Fitur Output & Deduplikasi

Save Mode — Format Penyimpanan

Chirei mendukung tiga mode penyimpanan hasil scraping yang bisa dipilih melalui dropdown Save Mode di toolbar atas:

JSON

Menyimpan hasil scraping ke file JSON lokal di folder output/. Setiap run menghasilkan file baru dengan format {config_name}_{timestamp}.json. File bisa diakses dan diunduh melalui tab Files di History.

MongoDB

Menyimpan hasil ke collection scraped_items di MongoDB. Menggunakan bulk upsert — jika item dengan _url yang sama sudah ada, data langsung di-update tanpa duplikasi.

Both (Keduanya)

Simpan ke JSON file dan MongoDB sekaligus. Cocok untuk backup lokal sambil tetap mendapatkan keuntungan queryable database MongoDB.

Output Mode — Struktur Data

Dropdown Output Mode di toolbar menentukan bagaimana data hasil scraping disusun:

Flat

Semua item dari semua langkah pipeline digabung menjadi satu array datar. Setiap item memiliki field _source_branch yang menandai dari node mana data berasal. Cocok untuk export ke CSV atau analisis tabular.

Nested

Data disusun secara hierarkis sesuai pipeline. Item dari Listing node memiliki field children yang berisi data dari Detail/Fan-out nodes. Cocok untuk mempertahankan relasi parent-child antar halaman.

Contoh Flat:

[
  { "Judul": "Artikel A", "Link": "https://...", "_source_branch": "Listing" },
  { "Content": "Isi artikel A...", "_source_branch": "Detail" },
  { "Judul": "Artikel B", "Link": "https://...", "_source_branch": "Listing" }
]

Contoh Nested:

[
  {
    "Judul": "Artikel A",
    "Link": "https://...",
    "children": {
      "Detail": [
        { "Content": "Isi artikel A..." }
      ]
    }
  }
]

Deduplikasi URL (Ceklis Dup)

Checkbox Dup di toolbar mengontrol apakah item yang sudah pernah di-scrape akan diambil lagi atau di-skip:

Dup Tidak Dicentang (Default)

Mode deduplikasi aktif. Setiap URL yang berhasil di-scrape disimpan hash SHA-256-nya ke tabel seen_urls. Pada run berikutnya, URL yang sudah pernah diambil akan otomatis di-skip dan masuk hitungan skipped_items.

Dup Dicentang

Izinkan duplikat. Semua item akan diambil ulang tanpa pengecekan hash. Berguna saat konten halaman berubah secara berkala dan Anda ingin mengambil versi terbaru setiap kali scraping dijalankan.

Cara Kerja Deduplikasi:

Langkah	Proses
1. Hash URL	Setiap `_url` dari item yang di-scrape di-hash menggunakan SHA-256.
2. Cek Database	Hash dibandingkan dengan tabel `seen_urls` menggunakan query batch (`url_hash = ANY(%s)`) untuk efisiensi.
3. Filter	Item dengan hash yang sudah ada di-skip (counter `skipped_items` bertambah). Hanya item baru yang dilanjutkan ke detail page scraping.
4. Simpan Hash	Hash URL baru disimpan ke `seen_urls` dengan compound key `(url_hash, config_id)` untuk isolasi per-config.

Fitur Menjalankan Scraper

Memulai Scraping

Setelah konfigurasi (URL, fields, pagination) selesai, klik tombol ⚡ Run di toolbar kanan atas untuk memulai proses scraping.

1

Klik Tombol Run

Tombol Run akan otomatis menyimpan konfigurasi (jika belum tersimpan) lalu mengirimkan task ke Celery worker queue. Sebuah toast notifikasi "Scraping (N steps)..." akan muncul di pojok kanan bawah.

2

Monitor Progress Toast

Toast menampilkan progress bar animasi dan pesan status yang berubah secara berkala: Sending to Queue → Booting worker → Fetching pages → Extracting data → Following links. Timer menunjukkan durasi berjalan.

3

Scrape Complete

Setelah selesai, toast berubah menjadi hijau dengan ringkasan: jumlah item baru dan item yang di-skip. Klik View Data untuk langsung melihat data.

Live Log Stream

Chirei menyediakan modal log real-time yang menampilkan setiap langkah scraping secara live via WebSocket.

Live Streaming

Saat task berstatus running atau queuing, Chirei membuka koneksi WebSocket ke /ws/logs/{id} dan menampilkan setiap baris log secara real-time.

Log Parsing

Log diformat secara otomatis untuk membedakan antara info sistem, error, dan data yang berhasil diekstrak.

Klik tombol ≡ Logs pada history card untuk membuka modal log. Contoh output log:

Run History

Tab History menampilkan semua riwayat eksekusi scraping. Setiap run dicatat dengan metadata lengkap.

Filter Status

Filter riwayat berdasarkan status: All, Queuing, Running, Success, Failed, dan Cancelled.

Detail per Run

Setiap card menampilkan: nama config, waktu mulai, jumlah item baru & yang di-skip, status badge, dan tombol aksi (Logs, View Data, Cancel).

Cancel Task

Task yang masih berstatus queuing atau running bisa dibatalkan dengan tombol ■ Cancel.

Results & Data Viewer

Tab Results menyajikan data yang berhasil di-scrape dalam format tabel interaktif.

1

Tabel Hasil Scraping

Kolom tabel dibangkitkan otomatis berdasarkan field yang di-mapping. Data ditampilkan per baris dengan ringkasan di header: jumlah item baru dan skipped.

2

Nested Data (JSON Tree)

Jika data memiliki struktur nested (array/object), Chirei merendernya sebagai collapsible JSON tree yang bisa di-expand langsung di dalam tabel.

JSON Output Files

Tab JSON Files menampilkan daftar semua file output hasil scraping pada server.

File Naming

Format nama file: {config_name}_{timestamp}.json. Contoh: blog_20260330_045017.json

Preview Data

Klik file mana saja untuk langsung membuka isinya di tab Results — tanpa perlu download atau membuka editor eksternal.

Pengenalan Sistem Chirei