A Discord bot for managing a book club's shared knowledge base (commonbase). Members can store quotes, thoughts, and reading lists while the bot tracks books and provides multi-turn conversations for context gathering.

• /store - Store an entry to the Commonbase with book autocomplete
• /cr - Manage your currently reading list (add, list, mark finished)
• /bookshelf - Link to the shared bookshelf web interface
• /graph - Link to UMAP visualization of entries
• /ocr - Extract text from images with selection interface

• React with ➕ to any message to add it to the Commonbase

• Use >> quote [[book title]] to quickly add quotes with book references

• Use [[book title]] anywhere in messages to create clickable links to the bookshelf
• Supports multiple book mentions in one message
• Example: "I just read [[Dune]] and think it's better than [[I, Robot]]"

• Book source clarification when information is missing
• OCR text selection interface
• Book selection from multiple matches

1. Install Dependencies

   npm install

2. Discord Bot Setup

   Create Discord Application & Bot:

   1. Go to Discord Developer Portal
   2. Click "New Application" and give it a name (e.g., "Book Club Bot")
   3. Go to the "Bot" section in the left sidebar
   4. Click "Add Bot" then "Yes, do it!"
   5. Enable Required Intents:
      • Scroll down to "Privileged Gateway Intents"
      • Enable "MESSAGE CONTENT INTENT" (required for reading message content)
      • Save changes
   6. Copy the Token - this is your DISCORD_TOKEN
   7. Go to "General Information" in the left sidebar
   8. Copy the Application ID - this is your DISCORD_CLIENT_ID

   Get Your Server ID:

   1. In Discord, go to Settings > Advanced > Enable Developer Mode
   2. Right-click your server name and "Copy Server ID" - this is your DISCORD_GUILD_ID

   Set OAuth2 Redirect (Required):

   1. In Developer Portal, go to "OAuth2" > "General"
   2. Add a redirect URI: http://localhost:3000/auth/callback
   3. Click "Save Changes"

   Note: This URL won't actually be used since the bot doesn't use OAuth2 login, but Discord requires at least one redirect URI to be set.

   Invite Bot to Server:

   1. Go to "OAuth2" > "URL Generator"
   2. Select scopes: bot and applications.commands
   3. Select bot permissions: Send Messages, Use Slash Commands, Read Message History, Add Reactions
   4. Copy the generated URL and visit it to add bot to your server

3. Environment Setup

   cp .env.example .env

   Fill in the values you just collected:

   DISCORD_TOKEN=your_bot_token_from_step_2.6
   DISCORD_CLIENT_ID=your_application_id_from_step_2.8
   DISCORD_GUILD_ID=your_server_id_from_step_2.2
   

4. PostgreSQL Database Setup

   Option A: Local PostgreSQL

   # Install PostgreSQL (macOS)
   brew install postgresql
   brew services start postgresql
   
   # Create database
   createdb discordbookclub
   
   # Your DATABASE_URL will be:
   DATABASE_URL="postgresql://username:password@localhost:5432/discordbookclub"
   # Replace username/password with your PostgreSQL credentials

   Option B: Docker PostgreSQL

   # Run PostgreSQL in Docker
   docker run --name bookclub-db -e POSTGRES_DB=discordbookclub -e POSTGRES_USER=bookclub -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres
   
   # Your DATABASE_URL will be:
   DATABASE_URL="postgresql://bookclub:password@localhost:5432/discordbookclub"

   Option C: Cloud PostgreSQL (Supabase/Railway/Render)

   • Create a PostgreSQL instance on your preferred cloud provider
   • Copy the connection string they provide
   • It will look like: postgresql://user:pass@host:5432/dbname

5. Run Database Migrations

   npm run db:migrate
   npm run db:generate

6. Deploy Discord Commands

   npm run deploy

7. Start the Bot

   npm start
   # or for development
   npm run dev

To deploy your Discord bot on Render:

Create a render.yaml file in your project root:

services:
  - type: worker
    name: discord-bookclub-bot
    env: node
    buildCommand: npm install && npm run deploy
    startCommand: npm start
    envVars:
      - key: NODE_ENV
        value: production

Ensure your package.json has a start script:

{
  "scripts": {
    "start": "node src/index.js"
  }
}

1. Create PostgreSQL Database:
   • In Render dashboard, click "New +" → "PostgreSQL"
   • Choose a name (e.g., "bookclub-db")
   • Select region and plan
   • Copy the "External Database URL" for later

1. Create Worker Service:

   • In Render dashboard, click "New +" → "Background Worker"
   • Connect your GitHub repository
   • Configure:
     • Name: discord-bookclub-bot
     • Environment: Node
     • Build Command: npm install
     • Start Command: npm start

2. Set Environment Variables:

   • DISCORD_TOKEN - Your Discord bot token
   • DISCORD_CLIENT_ID - Your Discord application client ID
   • DISCORD_GUILD_ID - Your Discord server ID
   • DATABASE_URL - The PostgreSQL URL from step 2
   • BOOKSHELF_URL - URL to your bookshelf app (if deployed)
   • GRAPH_URL - URL to your visualization app (if deployed)
   • NODE_ENV - production

3. Deploy Commands:

   • After first deployment, run: npm run deploy in the Render shell
   • Or add as a build command: npm install && npm run deploy

Run migrations after deployment:

npm run db:migrate
npm run db:generate

You can run these in the Render shell or add them to your build process.

• Render automatically deploys when you push to your connected Git branch
• The bot will restart automatically if it crashes
• Check the Render logs if you encounter issues
• Consider using Render's health checks for better reliability

• DISCORD_TOKEN - Your Discord bot token
• DISCORD_CLIENT_ID - Your Discord application client ID
• DISCORD_GUILD_ID - Your Discord server ID (optional, for guild-specific commands)
• DATABASE_URL - PostgreSQL connection string
• BOOKSHELF_URL - URL to your Next.js bookshelf app
• GRAPH_URL - URL to your UMAP visualization app

• Users - Discord user information
• Books - Book metadata (title, author, image, etc.)
• Entries - Quotes, thoughts, and reactions stored in the commonbase
• UserBooks - Reading status tracking (currently reading, finished)
• ConversationState - Multi-turn conversation management

/store content:"The fox went to the store" book:Dune

>> The fox went to the store [[Dune]]

1. Use /ocr with an image attachment
2. Bot extracts text and shows preview
3. Reply with specific text to save or "all" for everything
4. Specify which book the text is from

/cr add title:"Dune" author:"Frank Herbert" image:"https://example.com/cover.jpg"
/cr existing book:Dune
/cr list
/cr finished book:Dune

src/
├── index.js              # Main bot file
├── deploy-commands.js    # Command deployment script
├── commands/             # Slash command implementations
│   ├── store.js
│   ├── cr.js
│   ├── bookshelf.js
│   ├── graph.js
│   └── ocr.js
├── handlers/             # Event handlers
│   ├── messageHandler.js
│   ├── reactionHandler.js
│   └── conversationHandler.js
└── utils/
    └── commandLoader.js

This bot is designed for a 5-person book club reading ~5 books per month each. The commonbase stores all shared knowledge for later exploration and visualization.