Hypothesis Atlas/Documentation
ExplorerHome

Quick Start

Get Hypothesis Atlas running on your laptop in under two minutes.

1

Clone the repo

git clone https://github.com/your-org/hypothesis-atlas.git && cd hypothesis-atlas
2

One-command install

make laptop-install

Installs npm deps, creates .env, starts Docker (Postgres + Redis), pushes Prisma schema.

3

Start the app (two terminals)

make dev
make worker

Open http://localhost:3000

Architecture

Six layers, each independently replaceable.

Frontend

Next.js 14, React 18, Tailwind CSS

API

Next.js Route Handlers, Prisma ORM

Database

PostgreSQL (Neon / Supabase / Docker)

Queue

BullMQ + Redis (Upstash / Docker)

Worker

Separate process — Railway / Render

LLM

Groq API (llama-3.1-70b-versatile)

Environment & API Keys

Create a .env file at the project root. The install script creates one with defaults, but you should replace placeholder values.

DATABASE_URLrequired

PostgreSQL connection string. Local Docker uses port 5433.

DATABASE_URL="postgresql://postgres:postgres@localhost:5433/hypothesis_atlas?schema=public"
REDIS_URLoptional

Redis endpoint for BullMQ job queue. If omitted the app falls back to in-process setTimeout.

REDIS_URL="redis://localhost:6379"
GROQ_API_KEYrequired

Groq API key for LLM synthesis (llama-3.1-70b-versatile). Free tier available.

GROQ_API_KEY="your_groq_api_key_here"
Get a key at console.groq.com

Installation Details

What make laptop-install does under the hood.

Installs all dependencies listed in package.json. The postinstall hook auto-runs prisma generate.

Usage

How to use Hypothesis Atlas once it's running.

  1. Go to /explore and click a topic in the word cloud.
  2. Watch the real-time progress timeline as papers, datasets, and signals are fetched.
  3. When complete, explore the knowledge tree by clicking nodes.
  4. View methods, findings, disagreements, and open problems in the detail panel.

Deployment

Production architecture: Vercel (web) + Railway/Render (worker) + managed Postgres & Redis.

Set these environment variables in Vercel project settings:

DATABASE_URL=postgresql://...
REDIS_URL=redis://...
GROQ_API_KEY=your_groq_api_key_here
make deploy-web

Troubleshooting

Common issues and quick fixes.

FAQ

Frequently asked questions.

Pricing

Self-hosted

Free

Run on your own hardware under the MIT license. No limits.

Hosted

$1 / round

Run directly on our server. Each evidence-mapping round costs $1.

Payment integration uses Stripe. See the Pricing page for full plan details.

Hypothesis Atlas · MIT License · Home