# SLR Magic: System Architecture Blueprint

This document defines the global architectural design, data models, and module interactions across the **SLR Magic** workspace.

---

## 1. System Ecosystem Overview

The SLR Magic workspace coordinates systematic literature reviews (SLRs) through a local, laptop-first architecture. It prioritizes offline-capable local processes and file-based exchanges over complex network configurations (dropping requirements for custom VPN configurations, HAProxy reverse proxies, or centralized cloud databases).

The workspace comprises four active, complementary modules:
1. **Local Desktop Workspace Hub (`slr-ide/`)**: A local Next.js + SQLite application acting as the **one-stop solution** for the entire workflow. It handles project setup, reference ingestion, Python-based PDF matching/crawling, cloud syncing, 4-stage Gemini LLM screening, calibration pool assignment, and consensus Kappa metric calculation.
2. **Blinded Review Client (`inter-rater/`)**: An offline-capable React SPA that **facilitates blinded inter-rater review** sessions. Reviewers import rating packages, score papers independently using keyboard shortcuts, and export results back without seeing AI ratings or co-reviewer selections.
3. **Read-Only Snapshot Visualizer (`slr-viewer/`)**: An offline React SPA operating on Dexie.js (IndexedDB). It imports `.slr-viewer` snapshot datasets to render interactive 2D PRISMA 2020 flowcharts, 17 scientific ECharts panels, and LLM accounting breakdowns.
4. **FAIR Compliance Spreadsheet Database (`app-script/`)**: A Google Apps Script application operating within Google Sheets. It serves strictly as a **FAIR-compliant cloud database endpoint** to ingest finalized project results under zero Google OAuth app permissions.

```mermaid
graph TD
    subgraph "Local Desktop Environment (Laptop-First)"
        A[slr-ide: One-Stop Hub] <-->|SQLite Client| B[(Local SQLite DB)]
        A -->|1. Export Blinded .slr| C[inter-rater: Blinded SPA]
        C -->|2. Export Rated .slr| A
        A -->|3. Export Snapshot .slr-viewer| D[slr-viewer: Snapshot SPA]
        A -->|Spawn Subprocesses| E[Python Engine]
        E -->|Execute Entrypoints| F[match_cache.py / scrape_pdfs.py / main.py]
        F -->|JSON Output to Stdout| B
        B -->|SSE / ReadableStream Stream| A
        F -->|Write Local PDFs| G[pdf_library/repo/ & pdf_library/cached_pdf/]
        B -->|Rclone CLI Sync| H[Cloud Storage Google Drive / OneDrive]
    end
    
    A -->|4. Export FAIR CSV Ingestion| I[app-script: Google Sheets FAIR Database Sink]
    E -->|Upload matched PDFs| H
    A -->|Fetch shareable file links| H
```

---

## 2. Active Module Blueprints

### I. Local Desktop Workspace (`slr-ide/`)
*For details, refer to the module blueprint: [slr-ide/architecture.md](slr-ide/architecture.md)*

*   **Role**: The one-stop control hub for the systematic review lifecycle.
*   **Frontend Core**: Next.js App Router, React, and Tailwind CSS v4. Operates through a clean modular architecture separating functional Views (`DashboardView`, `PipelineExecutionView`, `InsightExportView`, etc.) and Custom Hooks (`useProjects`, `usePapers`, `usePipeline`, etc.) from the main `page.tsx` entry point.
*   **Persistence**: SQLite database (`db/slr.db`) for multi-project segmentation and paper metadata. Integrates with `prompt_templates` to store global/project prompts and JSON Schemas, `llm_pricing` to compute token costs, and `api_key_vault` for encrypted credential storage.
*   **Pipeline & Execution Engine**: Spawns Python Engine subprocesses for scraping, matching, vector indexing, and 4-stage Gemini LLM screening. Hosts a Centralized Pipeline Dashboard orchestrating Web Scraping (`scrape_pdfs.py`), Turbovec vector searches (`vector_worker.py`), Cloud Syncing (`rclone`), and Semantic LLM Screening (using Google Gemini's stateful Interactions API) via live SSE terminal streams and process recovery endpoints.
*   **Credential Vault & Audit Logs**: API keys are encrypted at rest via AES-256-GCM + PBKDF2 derived from a user-provided master password cached in-memory. Every model execution writes to an immutable database audit log table capturing interaction IDs, telemetry costs, and raw payloads.
*   **Cloud Gateway**: Subprocess execution of `rclone` to compress and upload local PDFs to project-scoped Drive/OneDrive folders and retrieve shareable file links.

### II. Inter-Rater Blinded Review SPA (`inter-rater/`)
*For details, refer to the module blueprint: [inter-rater/architecture.md](inter-rater/architecture.md)*

*   **Role**: Facilitates double-blind human rating reviews of calibration pools.
*   **Principles**: Offline-First & Serverless React Core using `localStorage` for browser-level persistence. Reviewer name variables and AI ratings are completely stripped from workflows to guarantee blinding.
*   **Interface**: Page-level scrolling layouts locking keyboard shortcuts (`I` / `E` / rules `1`-`9` / page navigation) alongside dynamic QA scoring fields and description templates.
*   **Standardized Schema**: Enforces whitelisted paper keys (including Abstract) and snake_case project metadata naming rules specifically for `CAL_Pool_A` sessions.

### III. Read-Only Dataset Snapshot Visualizer (`slr-viewer/`)
*For details, refer to the module blueprint: [slr-viewer/architecture.md](slr-viewer/architecture.md)*

*   **Role**: Interactive dashboard for presenting and analyzing exported `.slr-viewer` dataset snapshots.
*   **Principles**: Operates 100% offline in client browsers using Dexie.js (IndexedDB Wrapper) for dataset persistence and Apache ECharts 6 for visual rendering.
*   **Features**:
    - **2D PRISMA 2020 Canvas:** Interactive rendering of identification, screening, eligibility, and inclusion numbers with vector SVG & high-DPI PNG export.
    - **Cohort Visualizer:** 17 scientific chart types (Sankey flow diagrams, Stacked Bar, Radar, Line, Pie, Boxplot, Sunburst).
    - **LLM Spend & Accounting:** Per-stage cost grid and top expensive API call telemetry.

### IV. Google Sheets FAIR Database (`app-script/`)
*For details, refer to the module blueprint: [app-script/architecture.md](app-script/architecture.md)*

*   **Role**: Minimizes Google App security permission boundaries by acting strictly as a FAIR-compliant database sink.
*   **Ingestion**: Receives final reference CSV outputs exported from `slr-ide` to archive the systematically compiled literature dataset.
*   **Cohort Archiving**: Stores references under `00_Raw_Harvest` and copies selected papers to `05_Synthesis` for cloud indexing.

---

## 3. Data Ingestion & Sync Protocol

Literature reference data exchanges are synchronized using localized file-based exports and imports:

1. **Ingestion into slr-ide**: Project databases are initialized by importing research reference files (CSV/BibTeX) from external scholarly databases (Scopus, IEEE Xplore, Web of Science, PubMed, etc.).
2. **Blinded Review Exchange**:
   - `slr-ide` exports a blinded `.slr` JSON package containing snake_case metadata configuration details and whitelisted paper data (excluding AI decisions).
   - The reviewer imports this `.slr` file into `inter-rater`, ratings are entered locally, and the completed `.slr` file is exported back to `slr-ide` to auto-ingest reviewer decisions.
3. **Offline Snapshot Analysis**:
   - `slr-ide` exports project state into a `.slr-viewer` JSON snapshot file.
   - Stakeholders and peer reviewers import this snapshot into `slr-viewer` to explore PRISMA flowcharts, cohort statistics, and spend metrics offline.
4. **FAIR Database Ingestion**:
   - The completed database cohort is exported from `slr-ide` as a standard `.csv` file.
   - The user uploads this `.csv` file into the `app-script` Google Sheet workspace to populate the master `00_Raw_Harvest` and `05_Synthesis` sheets for FAIR storage compliance.