ai-bookmark

AI Bookmarklet

AI Bookmarklet is an AI-powered bookmark manager with a Chrome/Edge side panel, semantic search, and a FastAPI backend.

Structure

• extension/ — React/TypeScript MV3 extension
• backend/ — FastAPI + async SQLAlchemy + PostgreSQL
• frontend/ — Vite + React + TypeScript + Tailwind landing page
• docs/ — architecture, deployment, migration, and privacy documentation

Brand assets

• extension/public/logo-mark.svg — primary extension mark; icon-*.png files are the Chrome/Edge manifest sizes
• frontend/public/logo.svg and logo-on-dark.svg — light and dark frontend wordmarks
• frontend/public/favicon.svg — frontend favicon using the same mark

Prerequisites

• Node.js 18+
• Python 3.10+
• A local PostgreSQL service listening on localhost:5432
• Railway CLI for production deployment

The local PostgreSQL database uses:

user: postgres
password: postgres
database: ai_bookmark

Create the database if needed:

createdb -h localhost -p 5432 -U postgres ai_bookmark

Backend development

cd backend
./.venv/bin/pip install -e '.[test]'
cp env.template .env
alembic upgrade head
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/ai_bookmark \
  ./.venv/bin/uvicorn src.ai_bookmark_backend.main:app --reload --port 8080

Check the local API:

curl http://127.0.0.1:8080/health

Expected response:

{"status":"ok"}

Run backend tests:

cd backend
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/ai_bookmark \
  ./.venv/bin/python -m pytest -q

Extension development

cd extension
npm ci
npm run build

Load extension/dist from chrome://extensions or the Edge extensions page.

Set VITE_API_BASE_URL and the Firebase Web configuration (VITE_FIREBASE_API_KEY, VITE_FIREBASE_AUTH_DOMAIN, VITE_FIREBASE_PROJECT_ID, VITE_FIREBASE_APP_ID) in the ignored local production environment file before creating a store build. Add the Google and GitHub OAuth client IDs when those providers are enabled. The extension exchanges Firebase ID tokens for the product’s 7-day Bearer JWT; it does not carry Firebase ID tokens as its API session.

Railway deployment

The first project setup uses the Railway CLI:

railway login
railway init --name ai-bookmark-railway
railway add --database postgres
railway add --service backend-api
railway up ./backend --path-as-root --service backend-api
railway domain --service backend-api

Set DATABASE_URL as a Railway reference to the actual PostgreSQL service and store JWT, OpenRouter, Firebase Admin, GitHub OAuth, and CORS values as Railway variables. The public API domain is https://api.aibookmarklet.com.

Deploy the React landing page as a separate static service:

railway add --service frontend
railway up ./frontend --path-as-root --service frontend
railway domain aibookmarklet.com --service frontend
railway domain www.aibookmarklet.com --service frontend
railway domain api.aibookmarklet.com --service backend-api

The frontend uses Vite, React, TypeScript, Tailwind CSS, and Caddy. See docs/deployment-railway.md for the full deployment and rollback procedure.

Data migration

Use backend/scripts/migrate_to_postgres.py with a protected snapshot:

cd backend
./.venv/bin/python scripts/migrate_to_postgres.py \
  --input ../.migration/oss-snapshot \
  --dry-run

Do not delete the legacy source until the snapshot checksum, target counts, user login, and extension smoke tests have passed.