Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• vercel.json
• extension/vite.config.ts
• CHANGELOG.md
• extension/src/background/index.ts
• extension/src/background/api-client.ts

The Oddity 1 deployment process transfers the project from a local development environment to production-ready platforms. This guide covers the deployment of the Express API to Vercel and the packaging of the Chrome extension for the Chrome Web Store.

Sources: README.md:144-145, CHANGELOG.md:89-106

Backend Deployment (Vercel)

The backend is an Express API designed for deployment to Vercel. Vercel handles the server-side logic and environment variable management for production.

Vercel Deployment Steps

1. Push the repository to GitHub.
2. Import the project into the Vercel dashboard.
3. Set the root directory to backend/ or utilize the vercel.json file at the repository root.
4. Configure production environment variables in the Vercel dashboard.
5. Deploy the project; Vercel automatically applies rewrite rules defined in vercel.json.

Sources: README.md:147-152, vercel.json:1-12

Environment Variables

You must configure the following secrets in the Vercel dashboard to match the production environment:

Secret	Description	Source
SUPABASE_URL	Supabase project API URL	Supabase Dashboard
SUPABASE_ANON_KEY	Supabase anonymous API key	Supabase Dashboard
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key (Backend only)	Supabase Dashboard
OPENROUTER_API_KEY	API key for LLM services	openrouter.ai
OPENROUTER_MODEL	The specific model identifier	openrouter.ai

Sources: README.md:27-35, README.md:50-59

Post-Deployment Tasks

After Vercel provides a production URL, you must update the BACKEND_URL in packages/shared/src/constants.ts to point to the live API. The extension requires a rebuild following this change to establish a connection to the production backend.

Sources: README.md:154-155, extension/src/background/api-client.ts:8-10

Extension Deployment (Chrome Web Store)

The extension utilizes Vite and CRXJS for the build process. It must be compiled into a static distribution before submission to the Chrome Web Store.

Build and Package

1. Navigate to the extension/ directory.
2. Run npm run build to generate a production build.
3. Locate the generated files in the extension/dist/ folder.
4. Zip the contents of extension/dist/.
5. Upload the zip file to the Chrome Web Store Developer Dashboard.

Sources: README.md:157-160, extension/vite.config.ts:6-15

Deployment Workflow Diagram

The following diagram illustrates the parallel deployment paths for the backend and the extension.

This diagram shows the relationship between backend deployment and the final extension build.
Sources: README.md:147-160, CHANGELOG.md:118-125

Database and Authentication Setup

Production deployment requires a functional Supabase instance and Google OAuth configuration.

Supabase and OAuth Configuration

1. Supabase Tables: Ensure all tables (profiles, annotation_cache, user_annotations, annotation_feedback, site_adapters) are seeded and RLS policies are active.
2. Google OAuth: Enable the Google provider in the Supabase Dashboard under Auth > Providers.
3. Redirect URIs: Add the Supabase callback URL to the Google Cloud Console Authorized redirect URIs.
4. Client ID: Configure ODDITY_GOOGLE_OAUTH_CLIENT_ID in the backend environment and the extension build environment.

Sources: README.md:89-106, README.md:130-137, extension/src/background/index.ts:109-130

Extension Permissions

The production manifest must include necessary permissions for the extension to function across target sites.

Permission	Requirement
identity	Required for Google OAuth flow via Chrome Identity API
storage	Required to persist user preferences and auth tokens
scripting	Required for programmatic injection into PDF tabs
host_permissions	Set to <all_urls> to allow injection on visited pages

Sources: README.md:80-87, extension/src/background/index.ts:83-107

Final Verification Checklist

Before finalizing the deployment, verify the following:

• Prompts: Ensure backend/config/prompts.json contains actual system prompts instead of "<<PLACEHOLDER>>" values.
• API Health: Test the production endpoint at https://your-vercel-domain.vercel.app/api/health.
• Badge States: Confirm the extension icon shows a red "!" badge when not signed in and no badge when the production auth flow completes.
• PDF Functionality: Verify that file:// access is allowed in extension details if local PDF support is required.

Sources: README.md:108-124, README.md:183-188, extension/src/background/index.ts:402-405

This guide ensures the Oddity 1 system components are correctly configured and synchronized for production use. Failure to update the backend URL or environment variables will result in communication failures between the extension and the API.

Sources: README.md:190-205