✝️ Bible Companion

Open-source AI-powered Bible study application.

Built with Next.js 15 · Cloudflare Workers · Neon PostgreSQL · Clerk · Voyage AI

What is Bible Companion?

Bible Companion is a full-featured web application for reading, searching, and studying the Bible with AI assistance. Ask a question in natural language, and Bible Companion will:

Search scripture using semantic vector search (Cloudflare Vectorize + Voyage AI embeddings)
Retrieve relevant verses across 60+ Bible translations
Respond with context-aware answers powered by Cloudflare Workers AI (Llama 3.3 70B)
Cite specific verses and passages alongside every response

It runs as a Next.js frontend deployed on Vercel and a Python Cloudflare Worker backend that handles AI inference, vector search, and database operations. Authentication is handled by Clerk — users sign up and get a personalized experience with bookmarks, reading history, and preferences.

Screenshots

Landing Page

Bible Reader

Analytics Dashboard

Features

Bible Reader — Full Bible across 60+ translations with chapter/verse navigation
AI Chat — Ask questions about scripture; Normal mode for fast answers, Deep mode for semantic vector search with contextual responses
Semantic Search — Find verses by meaning, not just keywords, powered by Voyage AI embeddings and Cloudflare Vectorize
Voice Mode — Real-time spoken conversations about the Bible using LiveKit, Deepgram, and Cartesia
Bookmarks & Notes — Save verses with categories and personal notes
Multi-Language UI — Interface available in 11 languages (English, Spanish, French, German, Portuguese, Italian, Chinese, Korean, Japanese, Arabic, Swedish)
Progressive Web App — Install on any device, works offline for reading
3D Landing Page — Interactive Three.js scene on the home page
Dark Mode — Full light/dark theme support
Verse of the Day — Daily curated verse on the home page
Usage Analytics — Track your reading patterns and study habits
Notification System — Reading reminders and scheduled notifications

Project Structure

bible-companion/
├── src/
│   ├── app/                        # Next.js App Router
│   │   ├── page.tsx                # Landing page (/)
│   │   ├── layout.tsx              # Root layout (ClerkProvider, themes)
│   │   ├── middleware.ts           # Clerk auth middleware
│   │   ├── api/                    # API routes
│   │   │   ├── chat/route.ts      # AI chat endpoint
│   │   │   ├── search/route.ts    # Semantic search
│   │   │   ├── bookmarks/route.ts # Bookmark CRUD
│   │   │   ├── settings/route.ts  # User settings
│   │   │   ├── verse-of-the-day/route.ts
│   │   │   ├── notifications/     # Notification routes
│   │   │   ├── onboarding/        # Onboarding routes
│   │   │   ├── account/delete/route.ts
│   │   │   ├── stats/route.ts
│   │   │   ├── usage/route.ts
│   │   │   └── webhooks/clerk/route.ts
│   │   ├── bible/page.tsx          # Bible reader (/bible)
│   │   ├── chat/page.tsx           # AI chat (/chat)
│   │   ├── search/page.tsx         # Search (/search)
│   │   ├── bookmarks/page.tsx      # Bookmarks (/bookmarks)
│   │   ├── voice/page.tsx          # Voice mode (/voice)
│   │   ├── home/page.tsx           # Dashboard (/home)
│   │   ├── account/                # Account & usage analytics
│   │   ├── settings/page.tsx       # Settings (/settings)
│   │   ├── offline/page.tsx        # Offline reading
│   │   └── sign-in/, sign-up/     # Clerk auth pages
│   ├── components/
│   │   ├── ai-chat-interface.tsx   # Main AI chat component
│   │   ├── bible-reader.tsx        # Bible reading component
│   │   ├── bible-sidebar.tsx       # Navigation sidebar
│   │   ├── semantic-search.tsx     # Search component
│   │   ├── conversation-history.tsx
│   │   ├── language-selector.tsx   # i18n selector
│   │   ├── notification-center.tsx
│   │   ├── theme-provider.tsx      # Light/dark mode
│   │   ├── 3d/                     # Three.js 3D models (6 files)
│   │   ├── onboarding/             # Onboarding wizard (3 files)
│   │   ├── livekit-agent/          # Voice agent (Python/LiveKit)
│   │   │   ├── livekit_basic_agent.py
│   │   │   ├── Dockerfile
│   │   │   └── README.md
│   │   └── ui/                     # shadcn/ui primitives (22 files)
│   ├── hooks/                      # Custom React hooks
│   │   ├── useSearch.ts
│   │   ├── useUsageTracking.ts
│   │   ├── useUserPreferences.ts
│   │   ├── use-mobile.ts
│   │   └── use-button-feedback.ts
│   ├── lib/                        # Shared utilities
│   │   ├── workerApi.ts            # Cloudflare Worker API client
│   │   ├── cloudflare-accounts.ts  # Account configuration
│   │   ├── cloudflare-load-balancer.ts  # Worker client with retries
│   │   ├── db.ts                   # Neon PostgreSQL client
│   │   ├── bible-data.ts           # Bible data utilities
│   │   ├── multi-language-bible.ts # Multi-translation support
│   │   ├── verse-of-the-day.ts     # Daily verse logic
│   │   ├── notification-system.ts  # Push notifications
│   │   ├── usage-analytics.ts      # Usage tracking
│   │   └── utils.ts                # General utilities
│   └── types/
│       └── bible.ts                # TypeScript type definitions
│
├── bible-api-worker/               # Cloudflare Worker (Python)
│   ├── src/
│   │   └── entry.py                # Main worker — routes, AI, vector search, DB
│   ├── wrangler.toml               # Worker config (Workers AI, Vectorize bindings)
│   └── README.md
│
├── public/
│   ├── bibles/                     # 60+ Bible translation JSON files
│   ├── greeting-audio/             # Voice greeting MP3s (11 languages)
│   ├── models/                     # 3D model assets (GLTF)
│   ├── sw.js                       # Service Worker (PWA)
│   └── manifest.json               # PWA manifest
│
├── scripts/
│   ├── cli.mjs                     # Interactive CLI (setup, dev, deploy, status)
│   ├── migrate.js                  # Database migration (creates all tables)
│   ├── create-readmarks-table.js   # Readmarks table setup
│   └── count-translations.js       # Translation analysis utility
│
├── docs/                           # Additional documentation
├── .env.example                    # Environment variable template
├── LICENSE                         # Apache License 2.0
└── package.json

Prerequisites

Node.js 18+ (runtime & package manager)
A Clerk account for authentication — sign up free
A Neon PostgreSQL database — create free
A Cloudflare account — sign up free (for the backend worker + Vectorize)

Hosted Testing / Cloud Alternative

If you want to test the main Bible reader before running the project locally, use the hosted reader:

Hosted Bible reader: https://bible.axiestudio.se/bible

This is the fastest way to validate the core reading experience in the cloud before setting up your own local or production deployment. Use local setup when you need to change code or test environment-specific integrations.

Option	Use it for
`http://localhost:3000/bible`	Local development and code changes
`https://bible.axiestudio.se/bible`	Hosted testing and cloud-based smoke checks

Quick Start

1. Clone & Install

git clone https://github.com/YOUR_USERNAME/bible-companion.git
cd bible-companion
npm install

First time? Run npm run setup for an interactive setup wizard that walks you through environment configuration, dependency installation, and database migration.

2. Configure Environment

cp .env.example .env

Edit .env and fill in your credentials — see the Environment Variables section below.

3. Set Up the Database

npm run migrate

This creates all required tables (users, bookmarks, reading_history, user_settings, user_onboarding, reading_plans) in your Neon database.

4. Deploy the Cloudflare Worker

cd bible-api-worker
npm install
npx wrangler deploy

Set production secrets on the worker:

npx wrangler secret put DATABASE_URL
npx wrangler secret put CLERK_SECRET_KEY
npx wrangler secret put VOYAGE_API_KEY

5. Start the Dev Server

npm run dev

Navigate to http://localhost:3000 and start studying!

Environment Variables

Required

Variable	Description	Where to get it
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Clerk publishable key	clerk.com/dashboard
`CLERK_SECRET_KEY`	Clerk secret key	clerk.com/dashboard
`DATABASE_URL`	Neon PostgreSQL connection string	console.neon.tech
`NEXT_PUBLIC_WORKER_URL`	Deployed Cloudflare Worker URL	Output of `npx wrangler deploy`
`CLOUDFLARE_ACCOUNT_ID`	Cloudflare account ID	Dashboard → Overview
`CLOUDFLARE_API_TOKEN`	API token with Workers + Vectorize permissions	API Tokens
`VOYAGE_API_KEY`	Voyage AI API key (embeddings)	voyageai.com

Optional — Voice Mode

Variable	Description	Where to get it
`DEEPGRAM_API_KEY`	Deepgram STT/TTS key	console.deepgram.com
`CARTESIA_API_KEY`	Cartesia TTS key	cartesia.ai
`LIVEKIT_URL`	LiveKit WebSocket URL	cloud.livekit.io
`LIVEKIT_API_KEY`	LiveKit API key	cloud.livekit.io
`LIVEKIT_API_SECRET`	LiveKit API secret	cloud.livekit.io

Optional — Enhancements

Variable	Description
`NEXT_PUBLIC_APP_URL`	App URL (defaults to `http://localhost:3000`)
`CLOUDFLARE_VECTORIZE_INDEX`	Vectorize index name (defaults to `bible-embeddings`)

Available Commands

Interactive CLI

npm run cli              # Interactive menu — all commands in one place
npm run setup            # First-time setup wizard
npm run status           # Check project status & configuration

Development

npm run dev              # Start Next.js dev server (port 3000)
npm run build            # Build for production (runs migrations first)
npm start                # Start production server

Database

npm run migrate          # Run database migrations (creates all tables)

Code Quality

npm run lint             # ESLint
npm run lint:fix         # ESLint with auto-fix

Cloudflare Worker

cd bible-api-worker
npx wrangler dev         # Local development (port 8787)
npx wrangler deploy      # Deploy to Cloudflare

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        User's Browser                           │
│                    http://localhost:3000                         │
└─────────────────────┬───────────────────────────────────────────┘
                      │ Next.js pages + API routes
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│              Frontend (Next.js 15 + React 19)                   │
│                       Vercel                                    │
│                                                                 │
│  • Bible reader with 60+ translations                          │
│  • AI chat interface (normal + deep mode)                      │
│  • Semantic search                                             │
│  • Voice mode (LiveKit WebRTC)                                 │
│  • PWA with offline support                                    │
│  • Clerk authentication                                        │
└─────────────┬──────────────────────┬────────────────────────────┘
              │ HTTPS                │ WebRTC
              ▼                      ▼
┌──────────────────────────┐  ┌─────────────────┐
│  Cloudflare Worker       │  │  LiveKit Cloud   │
│  (Python)                │  │  (Voice Agent)   │
│                          │  │                  │
│  • AI chat (Workers AI)  │  │  • Deepgram STT  │
│  • Vector search         │  │  • Cartesia STT  │
│  • Bookmarks CRUD        │  │  • ElevenLabs TTS│
│  • User settings         │  │  • Workers AI LLM│
│  • Verse of the day      │  └─────────────────┘
│  • Voice processing      │
└──────────┬───────────────┘
           │
     ┌─────┼──────────┐
     ▼     ▼          ▼
┌────────┐ ┌────────┐ ┌──────────────┐
│  Neon  │ │Voyage  │ │  Cloudflare  │
│PostgreSQL│ │  AI   │ │  Vectorize   │
│        │ │Embeddings│ │  + Workers AI│
└────────┘ └────────┘ └──────────────┘

Voice Mode (Optional)

Voice mode enables real-time spoken conversations about the Bible. It requires additional API keys and a LiveKit agent.

Prerequisites

Deepgram account (speech-to-text / text-to-speech)
LiveKit Cloud account (WebRTC transport)
Cartesia account (alternative high-quality STT)
ElevenLabs account (alternative high-quality TTS)

Deploy the Voice Agent

cd src/components/livekit-agent
pip install -e .
python livekit_basic_agent.py

See src/components/livekit-agent/README.md for full setup and deployment instructions.

Deployment

Bible Companion deploys to Vercel (frontend) and Cloudflare Workers (backend) — both have generous free tiers.

If you only need a cloud-hosted way to test the reader before deploying your own stack, use https://bible.axiestudio.se/bible as the managed test environment for the main /bible experience.

Deploy the Backend

cd bible-api-worker
npx wrangler login
npx wrangler deploy

# Set production secrets
npx wrangler secret put DATABASE_URL
npx wrangler secret put CLERK_SECRET_KEY
npx wrangler secret put VOYAGE_API_KEY

Deploy the Frontend

Deploy to Vercel via the Vercel CLI or connect your GitHub repository:

npx vercel --prod

Set environment variables in the Vercel dashboard (Settings → Environment Variables).

What You Get

Service	Runs on	Free Tier
Frontend	Vercel	100 GB bandwidth/month
Backend API	Cloudflare Workers	100K requests/day
Vector Search	Cloudflare Vectorize	30M vector dimensions stored
AI Inference	Cloudflare Workers AI	10K requests/day
Database	Neon PostgreSQL	0.5 GB storage
Authentication	Clerk	10K monthly active users

Security

Never commit .env — it is gitignored by default. Use .env.example as a starting template.
Production secrets for the Cloudflare Worker should be set via npx wrangler secret put <KEY>, not checked into source control.
If you suspect a key has been exposed, rotate it immediately in the relevant provider dashboard.

Contributing

Contributions are welcome! Please open an issue or pull request.

Fork the repository
Create a feature branch (git checkout -b feature/my-feature)
Commit your changes (git commit -m 'Add my feature')
Push to the branch (git push origin feature/my-feature)
Open a Pull Request

License

Apache-2.0

Built with Next.js · Cloudflare Workers · Neon · Clerk

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
bible-api-worker		bible-api-worker
docs		docs
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

✝️ Bible Companion

What is Bible Companion?

Screenshots

Landing Page

Bible Reader

Analytics Dashboard

Features

Project Structure

Prerequisites

Hosted Testing / Cloud Alternative

Quick Start

1. Clone & Install

2. Configure Environment

3. Set Up the Database

4. Deploy the Cloudflare Worker

5. Start the Dev Server

Environment Variables

Required

Optional — Voice Mode

Optional — Enhancements

Available Commands

Interactive CLI

Development

Database

Code Quality

Cloudflare Worker

Architecture

Voice Mode (Optional)

Prerequisites

Deploy the Voice Agent

Deployment

Deploy the Backend

Deploy the Frontend

What You Get

Security

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages