Refract

See research differently. From reading papers → to doing research.
An intelligent scientific paper reader with contextual research memory, two-column PDF reflow, interactive multi-modal annotations, and cross-paper literature synthesis.

---

What is Refract?

Reading scientific literature in static double-column PDF files is an outdated, high-friction experience. Citations require jumping back and forth, formulas lack clarity, annotations are siloed, and researchers continually rediscover concepts they have already encountered in previous papers.

Refract transforms static academic PDFs into structured, explorable, and interconnected research workspaces. It reconstructs two-column academic layouts into comfortable desktop-first typography, cross-references concepts against your personal reading history (Contextual Recall), groups literature into curated collections (Research Projects), and actively challenges findings with deep adversarial probing (Paper Interrogation Mode).

Same research. New representation.

---

The 8 Core Prisms

 ┌─────────────────────────────────────────────────────────────────────────────────────────┐
 │                                         REFRACT                                         │
 ├─────────────────────────────────────────┬───────────────────────────────────────────────┤
 │             READER SURFACE              │                RESEARCH ENGINE                │
 │  • High-Density Two-Column Reflow       │  • Contextual Recall ("You've Seen This")     │
 │  • Native KaTeX Math & Formula Render   │  • Research Projects / Collections            │
 │  • Vector & Bézier Multi-Modal Canvas   │  • Cross-Paper AI Literature Synthesis        │
 │  • Interactive Bidirectional Citations  │  • 🕵️ Paper Interrogation Mode (Critical)      │
 │  • Embedded Figures with Lightbox Zoom  │  • Multi-Tenant Security & OAuth Isolation    │
 └─────────────────────────────────────────┴───────────────────────────────────────────────┘

1. 📑 High-Density Two-Column PDF Layout Reflow

• Layout Reconstruction: Automatically separates dual-column scientific PDFs into clean, readable linear sections (Introduction, Methods, Evaluation, etc.) while preserving source text fidelity.
• Formulas & Math: Native LaTeX equation rendering powered by KaTeX (<MathRenderer>).
• Interactive Citations: Hover over inline citation tags ([Vaswani et al., 2017]) to preview bibliographic details; click to jump directly to references with a persistent "Return to citation" button.
• Embedded Figures & Captions: Automatic image extraction and caption alignment with page markers and lightbox zoom.
• Original PDF View: Instant side-by-side or modal comparison against the raw uploaded PDF.

2. 🧠 Contextual Recall ("You've Seen This Before")

Refract remembers what you've encountered across your research.

• Heuristic Concept Detection: Fast rule-based extractor identifies technical terms, acronyms (RAG, LoRA, MAMBA), and hyphenated compound methods while filtering generic academic stopwords.
• Multi-Source Cross-Referencing: Connects the text you're reading against four personal research memory sources:
  1. Past Highlights: Exact quotes and sections highlighted in earlier papers.
  2. Past Notes: Sticky notes, margin thoughts, and markdown commentary.
  3. Past Ask Refract Queries: Previous AI questions and verified explanations.
  4. Library Papers: Other papers in your library discussing the same topic.
• Seamless Surfaces: Quiet corner recall cards, on-demand navigation triggers, and slide-over context drawers with deep links jumping directly to the anchor location.

3. 📁 Research Projects / Collections

From reading papers → to doing research.

• Thematic Collections: Curate papers around research questions (e.g., "Modern Transformer Architectures", "Agentic Tool Use", "Diffusion Optimization").
• Zero-Duplication Association: Papers link via ResearchProjectPaper join rows. A single paper can belong to multiple projects simultaneously without duplicating files, sections, or database records.
• Shelf Integration: Dedicated "Projects" tab on the home page with custom color palettes, aggregate paper counts, highlight totals, and note counts.

4. 🔬 Dedicated Project Workspace (/project/[id])

Each project provides a dedicated 5-tab research environment:

• Overview: Reading progress distribution (unread / in-progress / completed), extracted recurring themes across project papers, and quick query suggestions.
• Papers: Comprehensive table of papers with progress bars, annotation counts, "Open in reader" shortcuts, and paper removal.
• Notes: Chronological aggregated stream of all sticky notes and comments across every paper in the project with deep links (/paper/[id]?annotationId=[id]).
• Highlights: Aggregated highlights feed with color swatches, quoted excerpts, and reader deep links.
• Ask this Project: Cross-paper literature synthesis answering broad comparative questions with verified citations.

5. 🤖 Grounded Cross-Paper AI Synthesis

• Multi-Scope Inquiry Engine (lib/ai/query-engine.ts): Reusable architecture supporting focused passage questions, full-paper inquiries, and multi-paper project synthesis.
• Source-Grounded Prompting: Compiles candidate paper sections, user notes, and personal highlights into structured context prompts.
• Groq LLM Cascading: Primary execution with candidate fallback (llama-3.3-70b-versatile, qwen/qwen3.8-27b, llama-3.1-8b-instant).
• Deterministic Offline Fallback: Graceful heuristic synthesis when GROQ_API_KEY is not configured, ensuring uninterrupted local development.
• Verified Citations: Server-Sent Events (SSE) streaming with clickable citations ([Paper Title · Section 3.2]) taking you directly to the relevant passage in the reader.

6. 🎨 Multi-Modal Vector Annotation Canvas

• 5 Supported Modalities:
  1. Text Highlights: High-precision character range markups with customizable color swatches.
  2. Freehand Strokes: Smooth SVG <path> vectors using quadratic Bézier curve interpolation (pen and pencil modes).
  3. Geometric Shapes: Bounding boxes, rectangles, ellipses, and directional arrows.
  4. Pinned Sticky Notes: Anchored comment pins with rich Markdown support.
  5. Typography Overlays: Editable, resizable in-situ text boxes.
• Guest-to-Authenticated Claiming: Annotations created as an anonymous guest (tracked via secure cookie) are automatically merged into your permanent account upon Google login.

7. 📚 Permanent Multi-State Research Shelf

• Lifecycle State Machine:

  [ Upload Paper / Save arXiv ]
                │
                ▼
            ┌───────┐
            │ INBOX │ (Unread queue: progress = 0%)
            └───┬───┘
                │ User opens & reads
                ▼
           ┌─────────┐
           │ READING │ (Tracks scrollPosition, lastSection, progress %)
           └───┬─────┘
                │ User finishes (progress >= 90%)
                ▼
          ┌───────────┐
          │ COMPLETED │ (Recorded with completedAt timestamp)
          └───────────┘
  

• Single Source of Truth: Cloud SQLite / PostgreSQL via Prisma. Browser localStorage is never relied upon as a source of truth.
• Save First, Process Later: Raw uploads save fast metadata immediately to the Inbox; heavy layout, equation, and figure extraction run on-demand when first opened.
• Private Storage Isolation: Non-owners cannot access private paper uploads, stream private PDFs, or query Ask Refract.

8. 🕵️ Paper Interrogation Mode ("Don't Just Read. Interrogate.")

Don't just read the paper. Interrogate it.

Refract actively challenges academic literature rather than merely summarizing it:

• 7-Category Adversarial Probing:
  1. Assumptions: Unstated dependencies, structural bounds, unproven premises.
  2. Evidence: Verbatim grounded excerpts evaluating whether findings are directly supported, partially supported, inferred, or not established.
  3. Methodology: Experimental validity, baseline fairness, hyperparameter sensitivities.
  4. Limitations: Disclosed caveats vs unaddressed blind spots.
  5. Missing Experiments: Absent controls, omitted ablations, missing baselines.
  6. Claims: Precision mapping of what was actually proven vs exaggerated in the abstract/conclusion.
  7. Open Questions: High-value scientific avenues that challenge the findings.
• Interactive Multi-Pane Investigation Board:
  • Filter across 7 categories and status (UNREVIEWED, INVESTIGATING, INVESTIGATED).
  • Structured callouts: "Why this matters" & "What the paper does not establish".
  • Direct passage grounding: Clicking "Jump to passage" scrolls directly to the verbatim excerpt in the reader and flashes the paragraph.
  • Action suite: Ask Refract Follow-up, Challenge Analysis ("Show me the evidence"), and persistent Research Working Notes.
  • 6-Point Critical Summary: Synthesizes what is strongly supported, what remains uncertain, core assumptions, potential weaknesses, open questions, and the single most critical next investigation.

---

Tech Stack

Domain	Technology	Purpose
Framework	Next.js 14 (App Router, React 18)	SSR, dynamic routing, streaming SSE API routes
Language	TypeScript 5	End-to-end strict type safety
Styling	Tailwind CSS	Responsive, desktop-first design system
Database & ORM	SQLite + Prisma ORM	Multi-tenant schema, relations, and migrations
AI / LLM	Groq Cloud	Ultra-low latency streaming inference (Llama 3.3, Qwen)
Math Engine	KaTeX	Fast LaTeX equation and inline symbol rendering
PDF Extraction	pdf-parse, pdfjs-dist, pdf-lib	Geometry extraction, text streams, raster image slicing
Icons & UI	Lucide React	Clean research workstation iconography

---

Getting Started

Prerequisites

• Node.js: v18.17.0+ or v20+
• Package Manager: pnpm (recommended), npm, or yarn
• Poppler Utilities (optional for raster figure extraction):
  • macOS: brew install poppler
  • Ubuntu/Debian: sudo apt-get install -y poppler-utils

1. Clone & Install Dependencies

git clone https://github.com/devaniketh/Refract.git
cd Refract
pnpm install
# or: npm install

2. Environment Configuration

Create a .env.local file in the root directory:

cp .env.example .env.local

Example configuration:

# Database
DATABASE_URL="file:./dev.db"

# Groq Cloud API (Optional - deterministic offline fallback enabled when omitted)
GROQ_API_KEY="your_groq_api_key_here"
GROQ_MODEL="llama-3.3-70b-versatile"

# Google OAuth 2.0 (Optional - auto-authenticates as local researcher when omitted)
GOOGLE_CLIENT_ID="your_google_client_id"
GOOGLE_CLIENT_SECRET="your_google_client_secret"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

3. Initialize Database

pnpm db:push
pnpm db:generate

4. Start Development Server

pnpm dev
# or: npm run dev

Open http://localhost:3000 to view Refract.

---

Developer Runbook & CLI Commands

Refract includes automated scripts for development, schema management, architecture compliance, and integration testing.

# Development & Build
npm run dev                  # Start Next.js development server (http://localhost:3000)
npm run build                # Compile production Next.js build
npm start                    # Run production server
npm run typecheck            # Run TypeScript compiler check (tsc --noEmit)
npm run lint                 # Run ESLint validation

# Database & Schema
npm run db:push              # Push Prisma schema changes to database (idempotent)
npm run db:generate          # Generate Prisma Client bindings
npm run db:validate          # Validate prisma/schema.prisma integrity

# Architecture Compliance
npm run architecture:update  # Synchronize ARCHITECTURE.md with latest routes & models
npm run architecture:audit   # Audit codebase alignment against ARCHITECTURE.md (0-tolerance gate)

# Test Suites
npm test                     # Run all 7 test suites via runner
npm run test:projects        # Research Projects & Cross-Paper AI Synthesis (12 tests)
npm run test:recall          # Contextual Recall & Personal Research Memory (10 tests)
npm run test:annotations     # Multi-Modal Annotation Persistence & Session Claiming (11 tests)
npm run test:library         # Permanent Research Library & Multi-Tenant Privacy (14 tests)
npm run test:auth            # Google OAuth 2.0 Flow & Session Persistence (7 tests)
npm run test:routes          # Core HTTP API Route Handlers (11 tests)
npm run test:unit            # PDF Geometry & Parser Unit Tests

---

Unified CI Gate

Before committing code or deploying, Refract enforces a single Gate of Truth:

npm run ci

The unified CI gate executes:

1. typecheck (tsc --noEmit): Validates zero TypeScript errors.
2. lint (next lint): Validates zero ESLint warnings or errors.
3. db:validate (prisma validate): Validates Prisma schema integrity.
4. architecture:audit (scripts/architecture_audit.ts): Asserts 100% compliance with ARCHITECTURE.md.
5. test:all (scripts/run_all_tests.ts): Executes all 7 integration test suites.
6. build (next build): Validates full production bundle compilation and static generation.

---

Project Structure

Refract/
├── app/
│   ├── api/
│   │   ├── auth/            # Google OAuth flow, demo login, session validation
│   │   ├── papers/          # Upload, arXiv import, process, pdf stream, annotations, ask
│   │   │   └── [id]/projects/ # Paper-centric project membership management
│   │   ├── projects/        # Project CRUD, papers membership, cross-paper Q&A
│   │   │   └── [id]/
│   │   │       ├── ask/     # Streaming cross-paper literature synthesis
│   │   │       └── papers/  # Add/remove papers from collection
│   │   └── research/        # My Research shelf, reading tracker, contextual recall
│   ├── paper/[id]/page.tsx  # Interactive two-column reflow reader
│   ├── project/[id]/page.tsx# 5-tab Project Workspace
│   └── page.tsx             # My Research dashboard (Papers & Projects shelves)
├── components/              # Modular UI components (modals, toolbars, cards, readers)
├── lib/
│   ├── ai/                  # Groq client & cross-paper query engine
│   ├── pdf/                 # Two-column layout detector, figure/table extractors
│   ├── recall/              # Concept extractor & contextual memory service
│   ├── auth.ts              # Session cookies & Google OAuth helpers
│   ├── db.ts                # Prisma singleton & idempotent SQLite DDL
│   ├── storage.ts           # Serverless file persistence (/tmp/refract)
│   └── types.ts             # TypeScript domain interfaces & DTOs
├── prisma/
│   └── schema.prisma        # Complete relational database models
└── scripts/                 # Test suites, CI runners, and architecture auditors

---

License

Distributed under the MIT License. See LICENSE for more information.