jina-ai--reader/architecture.md

Architecture

Introduction

Jina Reader is an API-first SaaS application that turns URLs of web pages, PDFs, and other documents into markdown or images. It's built to help developers prepare data context for LLMs — now widely known as context engineering.

Application Architecture

Jina Reader is a multi-threaded Node.js application.

• Web pages are rendered using a headless Chrome browser, with text content extracted via a stack of techniques (see HTML to Markdown profiles).
• PDF parsing and rendering are done using PDF.js.
• MS Office documents are processed using LibreOffice.

Stateless Core Features

URL to Markdown / Image

Given a URL, Jina Reader fetches the content and renders it using headless Chrome if it's a web page (HTML/xHTML). If the content is a PDF, it uses PDF.js to parse and render. For MS Office documents, LibreOffice converts them to PDF + HTML first, after which the PDF/HTML path takes over.

Advanced options let you filter or manipulate the page content — CSS-selector-based filtering, custom JavaScript execution, custom proxy routing, and more.

HTML to Markdown

Reader can also take raw HTML and convert it to markdown, using the same conversion pipeline as the URL-to-Markdown feature.

PDF to Markdown / Image

Reader can take a PDF file, extract text content as markdown, and render each page as an image.

MS Office to Markdown / Image

Reader can take MS Office documents (Word, Excel, PowerPoint) and convert them to markdown or images by first converting them to PDF/HTML using LibreOffice.

Image to Text

Reader can take an image and produce a text description (captioning). This is built on the jina-vlm small vision-language model and can be extended to VQA tasks. Note: this is not exactly OCR.

Multiple URL-to-HTML Engines

Reader supports several engines for fetching/rendering web pages to HTML.

Browser

The most-used engine. The current implementation runs latest headless Chrome via the puppeteer library. It provides the most accurate rendering and can execute JavaScript on the page, which is essential for modern web pages.

CURL

A lightweight engine that uses curl-impersonate to fetch the raw HTML of a web page. It does not execute JavaScript. Reader's implementation includes a simulated cookie layer to handle basic cookie-based redirection.

CF-Browser-Rendering

Uses Cloudflare's Browser Rendering REST API for URL-to-HTML. Strict rate limits apply; this engine is meant for testing and as a fallback.

Auto

The default. Reader intelligently uses the CURL and Browser engines in combination, based on content characteristics and request requirements.

Multiple HTML-to-Markdown Profiles

Reader supports several profiles for converting HTML to markdown.

@mozilla/readability

Readability is automatically used to clean HTML before converting to markdown. It produces a clean, readable version of the HTML content for many pages.

Rule-based engine

A custom implementation inspired by the turndown library, with custom rules and plugins to convert HTML into markdown.

ReaderLM v2

An experimental engine that uses a specifically trained small language model to convert HTML to markdown.

ReaderLM v3 / JinaOCR / VLM

WIP / future engine that uses a vision-language model to convert webpage screenshots directly to markdown.

Abuse Mitigation (SaaS)

• Request filtering: block requests targeting suspicious addresses.
• Request throttling: cap concurrent requests per page.
• Anonymous-user pressure relief: when one URL receives excessive anonymous traffic, temporarily block that website for anonymous users.
• Excessive HTML nodes/depth: fall back to HTML-to-text instead of markdown.

Progressive Clustering

• Stage 0: fully stateless — no caching, no rate limit, no persistence.
• Stage 1: S3-like object storage for caching, no rate limit.
• Stage 2: MongoDB + S3-like object storage. MongoDB indexes the cached objects; rate limiting is available. This is the SaaS configuration and is not part of the open source branch.

Vendor-Provided Features

• Proxy: Reader supports a built-in proxy provider for fetching content via a different IP.
• SERP: Reader primarily relies on external SERP providers for web search results.
• VLM: Reader relies on a vision-language model for image captioning. The current model is gemini-2.5-flash-lite, but it can be switched to any model with similar capabilities.

Deployment Architecture

The SaaS version of Jina Reader is deployed as a Docker image on GCP Cloud Run. MongoDB Atlas is used for metadata indexing and rate limiting; Google Cloud Storage is used for cache data. Internal services and dependencies — such as billing, jina-vlm, and readerlm-v2 — are reached over a private VPC peering link.

We run two independent clusters: US and EU. The US cluster spans 3 regions (us-central1, us-east1, us-west1); the EU cluster runs in 1 region (europe-west1).

Due to the high resource requirements of headless Chrome and LibreOffice, Reader is best deployed on serverless platforms that handle auto-scaling and resource management.