TUTORIAL REPROCHEM V1.0.0
========================================
Data, Provenance, dan Reproducible Computational Research

A. INSTALASI WSL/UBUNTU
-----------------------
1. Simpan file:
       reprochem_1.0.0_all.deb

2. Jalankan:
       sudo apt update
       sudo apt install ./reprochem_1.0.0_all.deb

3. Jalankan aplikasi:
       reprochem

4. Buka browser:
       http://localhost:8808

5. Port lain, contoh 8813:
       REPROCHEM_PORT=8813 reprochem

6. Cek versi paket:
       dpkg -s reprochem | grep '^Version:'

B. LOKASI DATA
--------------
Data runtime tidak ditulis ke /opt. Default:
    ~/.local/share/reprochem/

Isi utama:
    reprochem.sqlite3
    objects/
    projects/
    imports/
    reports/
    backups/
    tmp/

Lokasi dapat diubah:
    REPROCHEM_HOME=/lokasi/baru reprochem

C. PRINSIP RAW OUTPUT
---------------------
Raw output adalah bukti primer.

Saat file diunggah:
1. ReproChem menghitung SHA-256.
2. Bytes disimpan pada content-addressed object store.
3. Hash diverifikasi setelah penulisan.
4. File object dibuat read-only bila OS mengizinkan.
5. Database menyimpan File ID, role, original name, SHA-256, size, MIME, dan lineage.

Parsed result TIDAK menggantikan raw output. Parser menghasilkan record baru yang
menunjuk kembali ke source_file_id.

D. MEMBUAT PROJECT
------------------
Menu:
    Project & Input -> Create Project

Isi:
- Project name
- Description
- Tags
- License / usage note

Setelah disimpan, project memperoleh Project ID unik.

E. MENAMBAHKAN MOLEKUL
----------------------
Menu:
    Project & Input -> Add Molecule

Data:
- Molecule name
- SMILES
- InChI
- charge
- multiplicity
- coordinates optional
- coordinate unit: angstrom/bohr/nm

Jika RDKit tersedia, SMILES divalidasi. ReproChem tidak mengubah struktur input
secara diam-diam.

F. CALCULATION SPECIFICATION
----------------------------
Menu:
    Calculation & Raw Output -> Register Calculation

Catat:
- Source module
- Program / engine
- Program version
- Driver / task
- Method / force field
- Basis
- Solvent / environment
- Convergence JSON
- Additional keywords JSON

Semua nilai disimpan menjadi Job Specification dan diberi spec hash.

PENTING TAMPILAN:
Job Specification TIDAK dirender dengan st.json. Panel menggunakan:
    background putih
    text #071B2F
    border teal/biru
    font monospace

Tujuannya agar tidak ada tulisan hitam di background hitam.

G. RAW OUTPUT DAN FILE PROVENANCE
---------------------------------
Menu:
    Calculation & Raw Output -> Raw Output

Role tersedia:
- raw_output
- input
- log
- manifest
- checkpoint
- trajectory
- spectrum
- descriptor
- other

Upload beberapa file sekaligus diperbolehkan.

H. IMPORT BUNDLE MODUL LAIN
---------------------------
Upload ZIP atau JSON dari project/module lain.

ReproChem mencari nama record umum seperti:
- integration_manifest.json
- manifest.json
- project.json
- job_spec.json
- result.json
- provenance.json

File bundle dan member-nya tetap diregistrasikan sebagai immutable evidence.
Isi JSON manifest disimpan sebagai provenance.

ReproChem TIDAK menebak field yang tidak tersedia.

I. PARSED RESULT
----------------
Menu:
    Calculation & Raw Output -> Parse Result

- JSON: disimpan sebagai document terstruktur.
- CSV: jumlah row, kolom, dan preview dicatat.
- Text: parser generik mencari sinyal energi/status secara heuristik.

Parser text bukan pengganti parser tervalidasi engine tertentu. Label parser dan
source_file_id selalu dipertahankan.

J. ENVIRONMENT SNAPSHOT
-----------------------
Menu:
    Calculation & Raw Output -> Environment

Snapshot berisi:
- ReproChem version/schema version
- Python version/executable
- OS/platform/machine
- CPU physical/logical
- total RAM
- NVIDIA GPU/driver jika nvidia-smi tersedia
- versi package Python
- CONDA_DEFAULT_ENV / VIRTUAL_ENV
- optional pip freeze

Klik "Store environment snapshot in provenance" untuk menyimpannya.

K. RESTART / CLONE CALCULATION
------------------------------
Menu:
    Calculation & Raw Output -> Restart / Clone

ReproChem membuat Calculation ID baru dengan parent_calculation_id menunjuk ke
calculation lama. Raw evidence lama tidak ditimpa.

L. DATABASE QUERY
-----------------
Menu:
    Database Query

Tersedia:
1. Project Tables
2. Search ID/name/method/file
3. Relationship Map
4. Raw SQL Read-only

Raw SQL hanya menerima satu SELECT atau PRAGMA.

M. INTEGRITY DAN AUDIT
----------------------
Menu:
    Integrity & Audit

Integrity Scan:
- PRAGMA integrity_check
- PRAGMA foreign_key_check
- re-hash semua object file
- bandingkan actual SHA-256 vs database

Duplicate Hashes:
- menemukan beberapa records dengan SHA-256 yang sama.

Audit Trail:
- tindakan, severity, message, details, timestamp.

Status & Error:
- registered
- queued
- running
- completed
- completed_with_warnings
- failed
- stopped
- archived

Error summary tidak menggantikan traceback/raw log; ia menjadi ringkasan yang dapat
dibaca manusia.

N. FAIR DATA DAN REPORT
-----------------------
Menu:
    FAIR & Laporan

FAIR-style metadata memuat identifier, name, description, keyword, license,
dates, distributions/files + SHA-256, module/measurement context, dan provenance note.

Generate Reports menghasilkan dari database yang sama:
- JSON
- CSV
- XLSX
- DOCX
- PDF
- portable ZIP

Portable ZIP berisi:
- project_record.json
- fair_metadata.json
- raw/
- tables/*.csv
- SHA256SUMS.txt
- README.txt

O. BACKUP, MIGRASI, RETENSI
---------------------------
Menu:
    Backup & Migrasi

Database Backup:
    salinan SQLite melalui sqlite3 backup API.

Project Backup:
    portable project ZIP.

Migration:
    ReproChem membuat backup database lebih dulu, kemudian menjalankan schema/index
    migration idempotent.

Retention Review:
    menandai file berdasarkan umur untuk ditinjau.

V1.0.0 TIDAK melakukan auto-delete raw evidence.

P. 20 CONTOH JURNAL VALID
-------------------------
Menu:
    Jurnal & 20 Contoh

Sumber:
Mobley DL, Guthrie JP.
FreeSolv: a database of experimental and calculated hydration free energies, with input files.
J Comput Aided Mol Des. 2014;28:711-720.
DOI: 10.1007/s10822-014-9747-x

File pendamping:
    ReproChem_20_Contoh_FreeSolv.csv

20 contoh menyimpan:
- compound_id
- name
- SMILES
- charge/multiplicity
- journal/DOI
- published context: GROMACS, GAFF, TIP3P, AM1-BCC

Guardrail:
Contoh hanya untuk demonstrasi provenance. Aplikasi tidak mengarang nilai hydration
free energy dan tidak menyatakan kalkulasi jurnal telah direproduksi.

Q. KONTRAS RUANG KANAN
-----------------------
Seluruh main/right pane dibuat khusus agar teks terlihat jelas:

Main background:       #FFFFFF
Normal text:           #10243E
Heading:               #071B2F
Table header:          light blue + dark text
Table body:            white + dark text
Input/select/textarea: white + dark text
Alert/expander/tabs:   light surface + dark text
JSON/spec:             white + dark monospace
Hero:                  dark background + white/yellow text

Tabel utama sengaja menggunakan HTML table dan tidak mengandalkan canvas st.dataframe.
Job Specification/JSON utama sengaja tidak mengandalkan st.json.
Dropdown portal yang dirender di luar main pane juga dipaksa putih + teks gelap.

Launcher DEB juga memberi theme Streamlit light, sehingga proteksi dilakukan pada dua
lapisan: Streamlit theme + CSS aplikasi.

Jika browser masih menyimpan CSS aplikasi lama setelah upgrade, gunakan Ctrl+F5.

R. SISTEM & VALIDASI
--------------------
Menu:
    Sistem & Validasi

Self-test memeriksa:
- workspace writable
- SQLite integrity / FK
- SHA-256 reference
- jumlah 20 contoh
- 20 SMILES dengan RDKit bila tersedia
- immutable object store
- UI visibility sample

S. MENJALANKAN FILE PY LANGSUNG
-------------------------------
    python ReproChem_V1.0.0.py

Aplikasi akan me-relaunch Streamlit otomatis pada port 8808.

Disable auto-pip:
    REPROCHEM_NO_AUTO_PIP=1 python ReproChem_V1.0.0.py

Copyright © Kasmui, 2026.
