Archival document transcription for non-technical researchers.

Upload batches of archival images → receive structured transcription packages.

Scribble empowers non-technical researchers to transcribe and natively translate image-based document collections at scale — no Python, no Jupyter, no local setup. Researchers upload batches of archival photographs and receive structured transcription packages by email and in their dashboard.

Designed for closed beta deployments (≤ ~20 users). Built on free-tier infrastructure.

• Multi-format ingest — JPEG, PNG, HEIC/HEIF (iOS native), PDF, ZIP
• AI provider routing — Gemini and OpenAI (direct or via institutional API portals)
• Flexible output — free-text narrative, structured CSV tables, or both
• Zero-shot translation — automatic translation of narrative text and data tables directly into a target language (default English)
• Cost estimation — pre-flight estimate before any API calls are made; adaptive feedback loop from real spend data
• Per-researcher budgets — hard cap enforced per-image; job pauses immediately at limit
• Email delivery — completion email with a signed download link for the output package
• Welcome emails — automated invite email with Google sign-in steps and a link to in-app help
• Admin dashboard — invite users, manage budgets, monitor spend, generate impersonation links
• Mobile-ready — HEIC uploads, responsive layout, bottom navigation on small screens

graph TD
    Browser[Browser / Next.js] -->|HTTPS + JWT| FastAPI[FastAPI Backend]
    FastAPI -->|JWT verification| SupabaseAuth[Supabase Auth]
    FastAPI -->|CRUD & RLS| SupabaseDB[Supabase Postgres DB]
    FastAPI -->|Upload / Download| SupabaseStorage[Supabase Storage]
    FastAPI -->|BackgroundTasks| Worker[Worker Thread]
    Worker -->|Paired OCR / Transcription| HUITGateway[HUIT Gemini / OpenAI Proxy]
    Worker -->|SMTP Notification| Gmail[Gmail SMTP Server]

Why BackgroundTasks instead of Celery/Redis? Zero broker overhead. Sufficient for ≤ 20 researchers with batches up to ~200 images. If a worker thread restarts, the recovery loop automatically resets active image states to pending on restart.

The active list is discovered dynamically and admin-curated, so it evolves over time. A model appears in the UI only if its provider's API key is configured. Representative examples:

Tags are assigned automatically by the model sync worker from naming conventions: Flash/Mini/Nano/Lite models → Fast, non-frontier workhorse models such as GPT 5.1 → Standard, and current frontier/SOTA models such as GPT 5.5 or Gemini 3.1 Pro → Premier. Admins still choose which discovered models are curated for users.

Note on Render tier: The free tier sleeps after 15 min of inactivity (cold start ~30s) and blocks outbound SMTP. The Starter plan ($7/mo) is always-on and unblocks port 465. Use UptimeRobot (free) to keep the free tier warm.

• Schema migrations applied from api/supabase/migrations/ in order
• Storage buckets created: job-images, deliverables (private)
• Vercel environment variables set
• Render backend environment variables set
• CORS_ORIGINS locked to exact Vercel URL
• Successful End-to-End Test (E2E) Job completed

git clone https://github.com/YOUR_USERNAME/scribble.git
cd scribble/app
cp api/.env.example api/.env   # fill in your values

1. Create a project at supabase.com
2. SQL Editor → run all SQL files in api/supabase/migrations/ in order
3. Storage → create two private buckets: job-images and deliverables
4. Auth → Providers → enable Google (primary sign-in); enable Email if you want admin-issued magic links
5. Auth → Settings → disable "Allow new users to sign up" to keep access invite-only
6. Note your Project URL, anon key, service_role key, and JWT Secret

1. New project → import your fork → Root Directory: web
2. Add environment variables:

NEXT_PUBLIC_SUPABASE_URL       = your Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY  = your Supabase anon key
NEXT_PUBLIC_API_URL            = your Render URL (fill after Step 4)

3. Deploy — note your Vercel URL

The support address shown in the UI is set in web/src/lib/constants.ts (SUPPORT_EMAIL); admin authorization is gated server-side by ADMIN_EMAIL on Render (Step 4), not in the frontend.

1. render.com → New → Blueprint → connect your fork
2. Render detects render.yaml — fill in secret env vars in the form
3. Set ADMIN_EMAIL = the email that should have admin access (must match a researcher's login email)
4. Set CORS_ORIGINS = your Vercel URL (no trailing slash)
5. Deploy — note your Render URL
6. Back in Vercel, set NEXT_PUBLIC_API_URL = your Render URL → redeploy

Add whichever keys you have to Render's environment:

# Institutional portal (e.g. Harvard HUIT)
HUIT_GEMINI_API_KEY    HUIT_GEMINI_BASE_URL
HUIT_OPENAI_API_KEY    HUIT_OPENAI_BASE_URL

# Direct keys
GOOGLE_API_KEY         # ai.google.dev
OPENAI_API_KEY         # platform.openai.com

Models without a configured key are automatically hidden from the UI — no code changes needed.

Configure Gmail SMTP in Render:

SMTP_USERNAME    your Google Workspace email
SMTP_PASSWORD    16-character App Password (Google Account → Security → App Passwords)
SMTP_FROM_EMAIL  Scribble <your@email.com>

If SMTP is not configured, jobs complete normally and results appear in the dashboard — email is simply skipped.

1. Navigate to /admin in the app.
2. Use Invite Researcher — enter email and set a starting budget.
3. The backend creates the user in Supabase Auth (auto-confirmed), provisions their profile, and automatically sends an invite email.
4. The user clicks Log In with Google in their email to log in via Google SSO (or requests a magic link).

Important: To enforce invite-only with Google SSO, disable "Allow new users to sign up" in Supabase Auth settings.

# Backend
cd api
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# Frontend (separate terminal)
cd web
npm install
npm run dev

Requires a running Supabase instance (supabase start) and a filled-in api/.env.

Each completed job produces a ZIP download containing:

Scribble — Harvard Library Digital Scholarship Program Matthew Cook · matt_cook@harvard.edu · library.harvard.edu/how-to/digital-scholarship-program