Paper Eater

Scientific paper digest web app for research analysts. Upload papers, extract structure, generate AI-assisted summaries, build concept maps, take notes with provenance, and create reports.

Quick Start

Prerequisites

• Node.js >= 20
• pnpm >= 9 (npm install -g pnpm)
• Docker and Docker Compose (for Postgres, Redis, MinIO)

Setup

# 1. Install dependencies
pnpm install

# 2. Start infrastructure (Postgres + pgvector, Redis, MinIO)
pnpm infra:up

# 3. Generate Prisma client
pnpm db:generate

# 4. Run database migrations
pnpm db:migrate

# 5. Seed demo data
pnpm db:seed

# 6. Start all services (web + api + worker)
pnpm dev

Access

• Web App: http://localhost:5173
• API: http://localhost:3001
• MinIO Console: http://localhost:9001 (minioadmin/minioadmin)

Demo Credentials

• Email: demo@papereater.dev
• Password: password123

Environment Variables

Copy .env and adjust as needed:

Variable	Default	Description
DATABASE_URL	postgresql://papereater:papereater@localhost:5432/papereater	Postgres connection
REDIS_URL	redis://localhost:6379	Redis connection
S3_ENDPOINT	http://localhost:9000	MinIO/S3 endpoint
S3_ACCESS_KEY	minioadmin	S3 access key
S3_SECRET_KEY	minioadmin	S3 secret key
S3_BUCKET	papereater	S3 bucket name
JWT_SECRET	(dev default)	JWT signing secret
LLM_PROVIDER	mock	LLM provider: mock, openai
OPENAI_API_KEY	(empty)	OpenAI API key (if provider=openai)
API_PORT	3001	API server port

Happy Path Demo Walkthrough

1. Sign up at http://localhost:5173/signup or log in with demo credentials
2. Create a project (e.g., "Kinase Research") or use the seeded "Kinase Inhibitor Research"
3. Add a paper:
   • Click "Upload PDF" and select any scientific PDF
   • Or click "Add from PMC" and enter a PMCID (e.g., PMC7096724)
4. Watch ingestion progress: Status updates from NEW → READY
5. Open the paper: See structured sections in the center pane
6. Use the Assistant (right panel):
   • Select "High-Level Summary" mode and send a message
   • Watch the streamed response with citations
   • Click "Save to notes" on any response
7. Try Concept Builder:
   • Switch to "Concept Builder" mode
   • Click an entity from the paper's entity list (or type one)
   • See a concept card generated
   • Add a second entity to see a relationship analysis
8. View Notes tab to see saved notes with provenance
9. Report Builder (/projects/{id}/reports):
   • Define section headings and guidance prompts
   • Click "Generate Report Draft"
   • Watch streamed output

Architecture

Monorepo Structure

apps/
  web/           # React + Vite + TailwindCSS frontend
  api/           # Fastify + tRPC API server
  worker/        # BullMQ worker for background jobs
packages/
  shared/        # Zod schemas, types, constants
  prompts/       # Prompt templates + mode registry
infra/
  docker-compose.yml   # Postgres, Redis, MinIO

Data Model

See apps/api/prisma/schema.prisma for the complete schema. Core concepts:

• Users/Projects/Papers: Multi-tenant project organization
• PaperSections/Figures: Structured content from ingestion
• Chunks: Text chunks for retrieval (pgvector-ready)
• Entities/EntityRelations: Extracted entities for concept builder
• Notes/NoteSources: Notes with provenance linking to sections/figures/messages
• AssistantSessions/Messages: Chat sessions with streaming
• Artifacts: Reusable outputs (summaries, walkthroughs, concept cards, reports)

Ingestion Pipeline

Papers go through a progressive pipeline managed by BullMQ:

NEW → FETCHING → QUICK_PARSE → STRUCTURE_PARSE → FIGURES → EMBEDDINGS → READY

Each step is a separate job:

• paper.fetch: Download from PMC (for PMC papers)
• paper.quick_parse: Fast text extraction via pdf-parse
• paper.structure_parse: Section detection and heading analysis
• paper.extract_figures: Caption and figure reference extraction from text
• paper.chunk_and_embed: Text chunking and entity extraction

Streaming

Assistant responses stream via Server-Sent Events (SSE):

1. Client sends message via tRPC mutation
2. Server starts async LLM generation, publishing tokens to Redis pubsub
3. Client connects to /api/stream/{runId} SSE endpoint
4. Tokens stream in real-time until done event

LLM Integration

Abstracted behind an LLMProvider interface:

• Mock mode (default): Returns realistic canned responses with citations for development
• OpenAI mode: Set LLM_PROVIDER=openai and OPENAI_API_KEY
• Easy to add Anthropic or other providers

Adding New Assistant Modes

1. Define the mode in packages/prompts/src/mode-registry.ts
2. Add the prompt template in packages/prompts/src/templates.ts
3. Add the enum value to the Prisma schema
4. Add UI for the mode in the assistant panel

Commands

Command	Description
pnpm install	Install all dependencies
pnpm dev	Start web + api + worker in dev mode
pnpm build	Build all packages
pnpm test	Run tests
pnpm infra:up	Start Docker services
pnpm infra:down	Stop Docker services
pnpm db:generate	Generate Prisma client
pnpm db:migrate	Run database migrations
pnpm db:seed	Seed demo data

Tech Stack

• Frontend: React 18, TypeScript, Vite, TailwindCSS, TanStack Query v4, Zustand, TipTap
• Backend: Node.js, TypeScript, Fastify, tRPC v10
• Database: PostgreSQL with pgvector, Prisma ORM
• Queue: Redis, BullMQ
• Storage: S3-compatible (MinIO in dev)
• Infrastructure: Docker Compose