Backend Integration

BrowseGenius now integrates with a Cloudflare Workers backend for cloud sync, user management, and cross-device access to your projects and test plans.

Features

• Cloud Sync: Projects and test plans automatically sync to the backend
• User Accounts: Secure authentication with subscription tiers
• Cross-Device: Access your data from any browser
• Screenshot Storage: Cloudflare R2 for efficient image storage
• API Credits: Track usage with built-in credit system

Setup

1. Create an Account

Sign up at the BrowseGenius API to get started:

# Using the API directly
curl -X POST https://api.browsegenius.com/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"your@email.com","password":"your_password","name":"Your Name"}'

You'll receive:

• User ID
• JWT token for authentication
• Initial API credits (100 for free tier)

2. Generate Extension API Key

Once logged in, create an extension API key:

curl -X POST https://api.browsegenius.com/api/v1/extension-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"name":"My Browser Extension"}'

Save the returned API key (format: bgx_...) securely.

3. Configure Extension

1. Open the BrowseGenius popup
2. Click the Settings icon
3. Enter your Extension API Key (starts with bgx_)
4. Click Save Keys

The extension will now sync your data automatically.

How It Works

Local-First Architecture

BrowseGenius uses a local-first approach:

• All operations work offline
• Data is stored in browser localStorage
• Changes sync to backend when online
• No data loss if backend is unavailable

Automatic Sync

Background sync runs every 5 minutes and:

• Uploads new projects to backend
• Syncs evals, phases, and test cases
• Fetches updates from other devices
• Updates user info (credits, subscription)

Data Flow

User Action (Create Eval)
       ↓
Local State Updated (Instant)
       ↓
API Call to Backend
       ↓
Backend Stores in D1 Database
  ├─ Evals (test_plans table)
  ├─ Phases (phases table)
  ├─ Test Cases (eval_test_cases table)
  └─ Test Results (eval_test_results table)
       ↓
Local State Marked as "Synced"

Eval Workflow

The new eval workflow follows this structure:

1. Create Eval - Initialize a new evaluation for a project
2. Discover Phases - Identify navigation sections (Dashboard, Settings, etc.)
3. Capture Screenshots - Take screenshots for each phase
4. Discover Tests - Generate test cases for each phase (up to 10 per phase)
5. Run Tests - Execute test cases and record results
6. Generate Report - Compile results across all phases

Data Hierarchy:

Project
  └─ Eval (Test Plan)
       ├─ Phase 1 (Dashboard)
       │    ├─ Capture 1
       │    ├─ Test Case 1
       │    ├─ Test Case 2
       │    └─ Test Results
       ├─ Phase 2 (User Management)
       │    ├─ Capture 1
       │    └─ Test Cases...
       └─ Phase N...

User Info Badge

When connected, the extension displays:

• Subscription Tier: Free, Pro, or Enterprise
• API Credits: Remaining credits for AI operations
• Refresh Button: Manually update user info

Subscription Tiers

Tier	API Credits	Projects	Test Plans	Support
Free	100/month	10	50	Community
Pro	1,000/month	Unlimited	Unlimited	Email
Enterprise	Custom	Unlimited	Unlimited	Priority

API Endpoints

The backend provides RESTful APIs for all operations:

Projects

• GET /api/v1/projects - List all projects
• GET /api/v1/projects/:id - Get single project
• POST /api/v1/projects - Create project
• PUT /api/v1/projects/:id - Update project
• DELETE /api/v1/projects/:id - Delete project
• POST /api/v1/projects/by-hostname - Get/create by hostname

Evals (Test Plans)

• GET /api/v1/test-plans?projectId=... - List evals for project
• GET /api/v1/test-plans/:id - Get eval with phases
• POST /api/v1/test-plans - Create eval
• PUT /api/v1/test-plans/:id - Update eval
• PATCH /api/v1/test-plans/:id/status - Update eval status
• DELETE /api/v1/test-plans/:id - Delete eval

Eval Statuses: new, discovering, testing, completed

Phases

Phases represent navigation sections within an eval (e.g., Dashboard, User Management).

• GET /api/v1/phases/eval/:evalId - List phases for eval
• GET /api/v1/phases/:id - Get phase details (includes test case count)
• POST /api/v1/phases - Create phase
• PUT /api/v1/phases/:id - Update phase
• PATCH /api/v1/phases/:id/status - Update phase status
• DELETE /api/v1/phases/:id - Delete phase

Phase Statuses: new, discovering, tests_discovered, tests_running, completed

Create Phase Example:

{
  "evalId": "eval-uuid",
  "name": "Dashboard Navigation",
  "navigationUrl": "/dashboard",
  "navigationGroup": "navbar",
  "orderIndex": 0
}

Test Cases

Individual test cases within a phase.

• GET /api/v1/eval-test-cases/phase/:phaseId - List test cases for phase
• GET /api/v1/eval-test-cases/:id - Get test case
• POST /api/v1/eval-test-cases - Create test case
• PUT /api/v1/eval-test-cases/:id - Update test case
• PATCH /api/v1/eval-test-cases/:id/status - Update test case status
• DELETE /api/v1/eval-test-cases/:id - Delete test case

Test Case Statuses: pending, running, passed, failed, skipped

Create Test Case Example:

{
  "phaseId": "phase-uuid",
  "title": "Verify dashboard loads correctly",
  "description": "Test that the dashboard page loads without errors",
  "steps": [
    "Navigate to /dashboard",
    "Wait for page to load",
    "Verify main widgets are visible"
  ],
  "expectedResult": "Dashboard displays all widgets without errors",
  "domSelector": ".dashboard-widget",
  "orderIndex": 0
}

Test Results

Execution results for test cases.

• GET /api/v1/eval-test-results/test-case/:testCaseId - Results for test case
• GET /api/v1/eval-test-results/phase/:phaseId - Results for phase
• GET /api/v1/eval-test-results/eval/:evalId - Results for eval
• GET /api/v1/eval-test-results/:id - Get single result
• POST /api/v1/eval-test-results - Submit test result
• GET /api/v1/eval-test-results/phase/:phaseId/stats - Phase statistics
• GET /api/v1/eval-test-results/eval/:evalId/stats - Eval statistics

Submit Result Example:

{
  "testCaseId": "test-case-uuid",
  "status": "passed",
  "executionTimeMs": 1250,
  "errorMessage": null,
  "screenshotR2Key": null
}

Result Statuses: passed, failed, error

Captures (Screenshots)

• POST /api/v1/captures/upload - Upload screenshot
• GET /api/v1/captures?projectId=... - List captures
• GET /api/v1/captures/:id - Get capture metadata
• GET /api/v1/captures/:id/image - Get image
• PATCH /api/v1/captures/:id - Update capture metadata
• DELETE /api/v1/captures/:id - Delete capture

Upload Capture (with Phase/Eval):

{
  "projectId": "project-uuid",
  "phaseId": "phase-uuid",
  "evalId": "eval-uuid",
  "imageData": "data:image/png;base64,...",
  "url": "https://example.com/dashboard",
  "title": "Dashboard Screenshot",
  "notes": "Initial state",
  "domSnapshot": {...}
}

User Info

• GET /api/v1/info - Get user info and credits

All requests require the X-Api-Key header:

curl https://api.browsegenius.com/api/v1/projects \
  -H "X-Api-Key: bgx_your_api_key_here"

Offline Mode

Without an Extension API Key:

• Extension works normally
• All data stored locally
• No sync to backend
• No cross-device access

This is perfect for:

• Privacy-sensitive work
• Air-gapped environments
• Testing without account

Troubleshooting

Sync Failures

Symptom: Projects not appearing on other devices

Solutions:

1. Check API key is correct in Settings
2. Verify backend is reachable: https://api.browsegenius.com/health
3. Check browser console for errors
4. Click refresh button in user badge
5. Try manual sync by reloading extension

Authentication Errors

Symptom: "Invalid or revoked extension API key"

Solutions:

1. Regenerate API key via backend
2. Clear localStorage and re-enter key
3. Verify key starts with bgx_
4. Check key hasn't been revoked

Credits Not Updating

Symptom: Credit count stays the same

Solutions:

1. Click refresh button in user badge
2. Wait for background sync (5 minutes)
3. Check subscription status
4. Contact support if credits should renew

Security

Data Protection

• API keys stored only in browser localStorage
• HTTPS encryption for all API calls
• Authentication required for all operations
• Keys scoped to single user

Best Practices

• Never share your Extension API Key
• Revoke unused keys regularly
• Use different keys for different browsers
• Keep backup of important projects

Privacy

• Screenshots stored in Cloudflare R2
• DOM snapshots never leave backend
• No analytics or tracking
• Data deleted on account closure

Migration from Local-Only

If you've been using BrowseGenius without backend:

1. Backup existing data: Export all projects and test plans
2. Set up account: Create account and get API key
3. Configure extension: Enter API key in settings
4. Verify sync: Check projects appear in backend
5. Cross-device: Install on other browsers with same key

Your local data will automatically upload on first sync.

Rate Limits

To ensure fair usage:

• 100 requests/minute per API key
• 10,000 requests/day per user
• Screenshot uploads limited to 10MB per file

Exceeded limits return 429 Too Many Requests.

Roadmap

Coming soon:

• Team sharing and collaboration
• Project templates
• Scheduled test execution
• Webhooks for CI/CD integration
• Real-time sync via WebSockets

Support

Need help?

• Check Troubleshooting
• View API Status
• Email: support@browsegenius.com
• GitHub Issues: Report Bug