Documentation

The included Docker Compose file spins up a local PostgreSQL instance. Run it and set your connection string.

pnpm dev:docker

Then set your POSTGRES_URL in .env.local:

POSTGRES_URL=postgresql://postgres:postgres@localhost:5432/chatbot

Drizzle provides a full migration toolkit. The most common commands:

The memory system uses PostgreSQL full-text search with a GIN index. Custom SQL files in lib/db/custom-sql/ are executed automatically after Drizzle migrations. The memory-fts-setup.sql file creates a search_memory function and a GIN index on to_tsvector('english', content). These scripts are idempotent — they are safe to run multiple times.

Generate a secret for signing sessions and tokens:

openssl rand -base64 32

Set it as BETTER_AUTH_SECRET in your .env.local. Also set BETTER_AUTH_URL to your application URL (http://localhost:3000 for local development).

The boilerplate supports two email verification methods, controlled by NEXT_PUBLIC_EMAIL_VERIFICATION_OPTION:

• otp — Users receive a 6-digit code via email. They enter it on the sign-in page to verify.
• magic_link — Users receive a clickable link that signs them in directly.

Both methods require a working Resend configuration to send verification emails.

When a user signs up, a Stripe customer is automatically created in the background. This ensures every user has a Stripe customer ID ready for when they subscribe to a paid plan. The organization onboarding flow is presented after first sign-up, allowing users to create or skip creating their first organization.

Sessions are stored in the database. A session hook automatically populates activeOrganizationId on login, so all subsequent queries are correctly scoped to the user's active organization.

You need at least one provider key to use the chatbot. Create accounts and generate API keys at:

• Anthropic — console.anthropic.com → set ANTHROPIC_API_KEY
• OpenAI — platform.openai.com → set OPENAI_API_KEY
• Google — aistudio.google.com → set GOOGLE_GENERATIVE_AI_API_KEY

When a conversation exceeds 60% of the active model's context window (minimum 50,000 tokens), the system automatically compresses older messages into a summary. The summary is cached in Redis with a 7-day TTL. The 6 most recent messages are always preserved in full. This keeps long conversations functional without ballooning token costs.

Sign up at serper.dev and set SERPER_API_KEY. The model can perform Google searches and receive up to 10 organic results with titles, snippets, and URLs. Serper also serves as the primary webpage scraper for the retrieve tool.

Sign up at exa.ai and set EXA_API_KEY. This tool finds semantically relevant text snippets across the web — returning 9 results with highlighted passages of up to 13 sentences each. It also serves as a fallback for webpage retrieval.

Sign up at jina.ai and set JINA_API_KEY. When the model needs to read a full webpage, a 3-provider fallback chain is used: Serper Scraper (17s timeout) → Exa → Jina AI. Content is truncated at 200K characters and summarized via GPT-4.1-mini if needed.

Anthropic and Google models include native code execution in a sandboxed Python environment. No additional API keys are needed. Code runs in the provider's own sandbox — no access to the filesystem or network.

To add a new tool, define it in lib/ai/tools/ using the Vercel AI SDK tool() helper, register it in the chat API route, create a result component in components/tool-results/, and add a rendering case in the message component. Tool keys use snake_case and map to tool-* part types in the message stream.

• Verification link — Magic link for email verification
• Verification OTP — 6-digit code for verification, sign-in, or password reset
• Organization invitation — Invite with accept button linking to the app
• Password reset — Reset link for forgotten passwords
• Contact form — Submission forwarded to the admin email

Templates live in lib/emails/templates/ and utility functions in lib/emails/utils.ts.

The webhook route at /api/webhooks/payments processes four event types:

• checkout.session.completed — First-time purchase. Updates the user with subscription fields and resets their token budget to 1,000,000.
• customer.subscription.updated — Plan changes or renewals. Syncs subscription fields and resets tokens.
• invoice.payment_succeeded — Confirms the plan is active.
• customer.subscription.deleted — Cancellation. Clears all Stripe fields and deactivates the plan.

For production, create a webhook endpoint in the Stripe Dashboard pointing to https://yourdomain.com/api/webhooks/payments and subscribe it to the four events above. Use the signing secret from the Dashboard (not the CLI) as your production STRIPE_WEBHOOK_SECRET.

Create a free Redis database at console.upstash.com. Copy the REST URL and token from the database details page into UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.

Requests are rate-limited using a sliding window algorithm via @upstash/ratelimit npm package:

• Free tier — 0 messages per 60 seconds (effectively blocked from sending messages)
• Paid tier — 10 messages per 60-second window

Each paid user gets a token budget of 1,000,000 tokens per billing cycle. Token counts are tracked in Redis under the key chatbot-usage:<userId>. The budget resets on subscription renewal. When a user exhausts their tokens, the API returns a 429 with error code rate_limit:insufficient_tokens.

When a conversation is compacted (summarized to fit within the context window), the resulting summary is cached in Redis under compaction:<chatId> with a 7-day TTL. This avoids re-summarizing the same messages on every request.

Create a volume (object storage) in your Railway project. Copy the bucket name, endpoint, region, access key, and secret key into the six FILE_UPLOAD_* environment variables listed in the Environment Variables section above. Set FILE_UPLOAD_RAILWAY_S3_FORCE_PATH_STYLE to true.

Since browsers upload directly to Railway, you need to configure CORS on the bucket. Install the AWS CLI and run:

aws s3api put-bucket-cors \
  --bucket FILE_UPLOAD_BUCKET \
  --endpoint-url FILE_UPLOAD_ENDPOINT \
  --cors-configuration '{
    "CORSRules": [{
      "AllowedOrigins": [
        "http://localhost:3000",
        "https://yourdomain.com"
      ],
      "AllowedMethods": ["POST", "PUT"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3600
    }]
  }'

Verify with aws s3api get-bucket-cors --bucket FILE_UPLOAD_BUCKET --endpoint-url FILE_UPLOAD_ENDPOINT. Remember to include all origins where your app runs (localhost for dev, production domain, any preview deployments).

Allowed MIME types: JPEG, PNG, WebP, GIF, and PDF. Maximum file size is 10 MB. Users can attach up to 10 files per message, with a concurrency limit of 10 simultaneous uploads. Files are stored with the key pattern chat-uploads/<userId>/<yyyy>/<mm>/<dd>/<uuid>-<filename>. These limits are configurable directly in code. However, the current default limits are reasonable for most use cases.

The upload process is fully automated. The client validates the file, calls /api/file-uploads/railway/prepare to get a presigned POST URL, uploads the file directly to Railway, and then creates a database record via trpc.file.create. The UI provides a queue with progress tracking, cancel, and retry.

• Owner — Full control. Can delete the organization, manage all members, and access everything.
• Admin — Can manage members, invitations, teams, and view org-wide usage.
• Member — Standard access. Can use the chatbot, manage own files, and view shared resources.

Within an organization, teams provide finer-grained grouping. Team admins can manage their team's members. File sharing can be scoped to specific teams rather than the entire org. Usage analytics can be filtered by team.

Organization owners and admins can invite users by email. Invitations are sent via Resend and include an accept button. The invitation page at /accept-invitation/[id] handles authentication gating — if the invitee isn't signed in, they're redirected to sign-in first.

The organization settings page includes a Usage tab with date range filtering, summary cards (messages sent, tokens used), a daily area chart powered by Recharts, and per-user breakdowns. Usage data is scoped to the active organization, team, or personal context.

The API is organized into eight routers with a total of 69 procedures:

Two procedure types are available: publicProcedure (no auth required) and privateProcedure (requires a valid session). Private procedures automatically extract the user's activeOrganizationId from the session, so all downstream queries are correctly scoped.

To add a new router, create a file in trpc/routers/, define your procedures using publicProcedure or privateProcedure, and register the router in trpc/routes.ts. The client automatically picks up the new types — no code generation step needed.

The fastest path to production. Connect your repository to Vercel and every push to your main branch will trigger an automatic deployment. Vercel natively supports Next.js — no build configuration is needed. Set your environment variables in the Vercel project settings and you're live.

A Dockerfile is included in the repository, allowing you to deploy anywhere Docker is supported — AWS ECS, Google Cloud Run, Fly.io, Railway, a VPS, or your own servers. Build and run the image:

# Using the compose.yml file
docker compose --profile app up --build
                  
# Or build the image manually and run the container
# Build the image
docker build -t nextjs-standalone-image .

# Run the container
docker run -p 3000:3000 --env-file .env.local -e NODE_ENV=production -e PORT=3000 nextjs-standalone-image

Pass your environment variables via --env-file or your platform's secret management. The container exposes port 3000 by default.

The choice of where to deploy your application is deceptively tricky, especially when it comes to AI Chatbots. You should consider your expected usage throughput and how it will affect your server(s).

What is your expected usage volume? AI Chatbots tend to make a lot of requests, all while streaming their responses to the client. The node.js server is kept busy waiting for tool calls to complete and for the token stream to finish. Depending on your use-case, a single request may consistently take 500 - 600 seconds to complete. It happened to me!

Regardless of where you choose to deploy your chatbot, you should strongly consider a choice that allows you to set up auto-scaling.