Prophet

AI-powered Chrome side panel extension with streaming chat, secure backend API, and credits-based billing. Built for developers who want a production-ready SaaS template with authentication, rate limiting, and AI integration.

Report Bug · Request Feature · Discussions

---

Screenshots

---

Table of Contents

• About
• Features
  • Chrome Extension
  • Backend & API
  • Developer Experience
• Screenshots
• Demo
• How It Works
• Built With
• Getting Started
  • Prerequisites
  • Installation
  • Environment Setup
  • Database Setup
  • Run Locally
  • Load Chrome Extension
  • Testing
• Project Structure
• Architecture
• Deployment
  • Deploy to Vercel
  • Production Checklist
• CI/CD
• Contributing
• Security
• Acknowledgments
• Star History
• Contact
• Support & Sponsor
• License
• Contributions

---

About

Prophet is a production-ready Chrome extension SaaS template that demonstrates how to build a complete AI-powered application with streaming chat, authentication, payments, and rate limiting. It features a side panel extension that communicates with a secure Next.js backend API powered by Anthropic's Claude AI.

Perfect for developers who want to:

• Ship a Chrome extension SaaS product quickly
• Learn modern full-stack architecture patterns
• Build AI-powered applications with streaming responses
• Implement credits-based billing with Stripe
• Scale from 0 to production with proper infrastructure

Features

Chrome Extension

• Side Panel Chat Interface: Native Chrome side panel with beautiful UI
• Streaming AI Responses: Real-time Claude AI responses with streaming
• Multi-Chat Support: Create, manage, and switch between multiple conversations
• Authentication Flow: Seamless Clerk authentication via web app
• Auto-Sync Sessions: Extension automatically syncs auth state
• Offline Support: Graceful handling of network issues

Backend & API

• Credits-Based Billing: Transparent pricing (1 credit = 1 cent API cost)
• Subscription Tiers: Free ($0.50), Pro ($11 + 10%), Premium ($35 + 17%), Ultra ($70 + 17%)
• Rate Limiting: Tier-based limits (Free: 5/min, Pro: 20/min, Premium/Ultra: 60/min) + global burst protection
• Streaming API: Server-Sent Events for real-time AI responses
• Webhooks: Clerk user sync + Stripe payment processing
• Token Tracking: Accurate usage monitoring with cost attribution

Developer Experience

• Monorepo Setup: pnpm workspaces for efficient package management
• Type Safety: End-to-end TypeScript with Zod validation
• Database Migrations: Drizzle ORM with version-controlled schema
• Testing: Vitest for unit and integration tests
• Linting & Formatting: ESLint + Prettier with pre-commit hooks
• Claude Code Skills: Comprehensive coding standards in .claude/skills/
• Hot Reload: Fast dev experience with Vite + Next.js

Demo

• Run locally: pnpm dev → Extension at localhost:5173, Marketing at localhost:3000
• Chrome Extension: Load apps/sidepanel/dist as unpacked extension
• Sign in via marketing site → Auth syncs to extension → Start chatting

Quick preview: Sign in → Open Prophet extension → Type message → Claude streams response → Credits deducted automatically

How It Works

1. User installs Chrome extension and clicks "Sign in via Prophet Website"
2. Opens marketing site in new tab, authenticates with Clerk
3. Clerk stores session in chrome.storage.local via extension sync
4. Extension detects session change → auto-reloads → user is logged in
5. User types message → Extension sends to /api/chat endpoint
6. Backend authenticates user, checks credits, validates rate limit
7. Streams request to Anthropic Claude API → proxies response back
8. Extension receives Server-Sent Events → displays streamed response
9. Backend tracks tokens, deducts credits, saves message to database
10. User can view chat history, manage subscription, purchase credits

Built With

Category	Technology
Framework	Next.js 16 (App Router)
Language	TypeScript (strict mode)
Styling	Tailwind CSS + shadcn/ui
State Management	Zustand + TanStack Query
Extension	Vite + CRXJS + React 18
Auth	Clerk v2.0 (web + extension)
Database	Supabase (PostgreSQL) + Drizzle ORM
AI Model	Anthropic Claude (Sonnet 4.5)
Rate Limiting	Upstash Redis (sliding window)
Caching	Upstash Redis (tier caching, 5min TTL)
Payments	Stripe (subscriptions + webhooks)
Validation	Zod
Build Tool	pnpm workspaces
Hosting	Vercel (recommended)

Getting Started

Prerequisites

• Node.js 20+
• pnpm 9+
• Accounts: Clerk, Supabase, Anthropic, Upstash Redis, Stripe

Installation

git clone https://github.com/ThanosKa/prophet.git
cd prophet
pnpm install

Environment Setup

See .claude/docs/setup.md for detailed instructions.

Quick setup:

# Marketing app (backend API)
cp apps/marketing/.env.example apps/marketing/.env.local
# Fill in: DATABASE_URL, ANTHROPIC_API_KEY, CLERK keys, UPSTASH keys, STRIPE keys

# Sidepanel extension
cp apps/sidepanel/.env.example apps/sidepanel/.env.local
# Fill in: VITE_CLERK_PUBLISHABLE_KEY, VITE_API_URL

Database Setup

pnpm db:migrate

Optional: Seed test data (auto-detects first user):

pnpm -F @prophet/marketing db:seed

Run Locally

# Start both apps in parallel
pnpm dev

# Or individually:
pnpm dev:web          # Marketing + API at localhost:3000
pnpm dev:sidepanel    # Extension dev server at localhost:5173

Load Chrome Extension

After building the sidepanel:

pnpm -F @prophet/sidepanel build

1. Open chrome://extensions
2. Enable "Developer mode" (top right)
3. Click "Load unpacked"
4. Select apps/sidepanel/dist folder
5. Click the extension icon to open the sidepanel

Testing

pnpm lint              # ESLint all apps
pnpm type-check        # TypeScript validation
pnpm test              # Run tests in watch mode
pnpm test:run          # Run tests once
pnpm test:coverage     # Coverage report

Project Structure

prophet/
├── apps/
│   ├── sidepanel/          # Chrome extension (Vite + React 18)
│   │   ├── src/
│   │   │   ├── components/ # React components
│   │   │   ├── hooks/      # Custom hooks
│   │   │   ├── store/      # Zustand stores
│   │   │   └── lib/        # Utilities
│   │   └── manifest.json   # Chrome extension manifest
│   ├── marketing/          # Next.js marketing + API
│   │   ├── app/
│   │   │   ├── api/        # API routes (chat, webhooks)
│   │   │   └── ...         # Pages and layouts
│   │   ├── components/     # React components
│   │   ├── lib/
│   │   │   ├── db/         # Drizzle schema, migrations
│   │   │   ├── ratelimit/  # Rate limiting logic
│   │   │   └── cache/      # Redis caching
│   │   └── scripts/        # Seed scripts
│   └── shared/             # Shared code
│       ├── types/          # Shared TypeScript types
│       └── utils/          # Shared utilities
├── .claude/
│   ├── docs/               # Detailed documentation
│   └── skills/             # Coding standards (topic-based)
└── .github/
    ├── workflows/          # CI/CD pipelines
    └── ISSUE_TEMPLATE/     # Issue templates

Architecture

Prophet uses a custom browser automation architecture built on accessibility tree snapshots and client-side tool execution via Chrome DevTools Protocol (CDP).

📖 For detailed technical documentation, see ARCHITECTURE.md

Quick Overview:

Monorepo Structure:

• apps/sidepanel - Chrome extension (Vite + React 18)
• apps/marketing - Next.js landing page + backend API (App Router)
• apps/shared - Shared types, utilities, Zod schemas

Data Flow: Extension → Backend API (/api/chat) → Anthropic API (streaming) → Backend → Extension

Why Client-Side Tool Execution?

• Tools execute in the Chrome extension (not backend) to access CDP
• CDP is only available in Chrome extensions - not on servers
• Enables automation in the user's logged-in browser session
• Backend never sees browsing activity (privacy + security)

Authentication:

• Clerk handles authentication across web app and Chrome extension
• Extension syncs session via chrome.storage.local
• Auto-reload on auth state changes

SaaS Model:

• Credits-based billing (1 credit = 1 cent API cost + 20% markup)
• Tiers: Free ($0.50), Pro ($11 +10%), Premium ($35 +17%), Ultra ($70 +17%)
• Stripe subscriptions with automatic credit allocation
• Non-expiring credits, roll over monthly

Security:

• ANTHROPIC_API_KEY never exposed to client (server-side only)
• All requests authenticated via Clerk middleware
• Rate limiting per tier + global burst protection (500 req/min)
• Input validation with Zod schemas
• Resource ownership verification on all queries

Caching:

• User tier cached in Redis (5min TTL) for fast rate limit checks
• Cache invalidation on Stripe/Clerk webhook events
• Reduces database load for high-traffic scenarios

Deployment

Deploy to Vercel

The easiest way to deploy Prophet is with Vercel:

1. Push your code to GitHub
2. Import the project in Vercel
3. Set root directory to apps/marketing
4. Add all environment variables from .env.local
5. Update NEXT_PUBLIC_APP_URL to your production domain
6. Deploy

Note: Only the marketing app (backend API) needs deployment. The Chrome extension runs client-side.

Production Checklist

• Configure production environment variables
• Set up Supabase connection pooling (Session mode recommended)
• Configure Clerk production instance and webhooks (/api/webhooks/clerk)
• Enable Stripe live mode with webhook endpoint (/api/webhooks/stripe)
• Set up Upstash Redis production instance
• Add production Clerk extension ID to Allowed Origins
• Configure custom domain and SSL
• Test all payment flows and webhooks
• Verify Chrome extension connects to production API
• Enable error tracking and monitoring
• Review rate limits and scaling strategy

CI/CD

.github/workflows/ci.yml runs automated checks on every push and pull request:

• ESLint for code quality
• TypeScript type checking (pnpm type-check)
• Uses Node.js 20 and pnpm 9 for consistency
• Skips builds (Vercel handles deployment)

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and follow our Code of Conduct. Use the issue templates for bugs and features, and the PR template when submitting changes.

Key areas for contribution:

• UI/UX improvements
• Performance optimizations
• Documentation improvements
• Bug fixes and security patches

Security

Report security vulnerabilities privately as described in SECURITY.md. Do not file public issues for security concerns.

Key security features:

• Server-side API key management
• Row-level security (RLS) migration available
• Rate limiting and abuse prevention
• Webhook signature verification
• Input validation and sanitization

Acknowledgments

• Anthropic for Claude AI
• Clerk for authentication
• shadcn/ui for UI components
• Vercel for hosting
• Next.js for the framework
• Drizzle for the ORM
• Upstash for serverless Redis

Star History

Contact

• GitHub Issues: Open an issue
• GitHub Discussions: Start a discussion
• Creator: @ThanosKa

Support & Sponsor

Documentation & Help:

• Architecture Guide: ARCHITECTURE.md - How Prophet's browser automation works
• Project Documentation: CLAUDE.md
• Claude Code Skills: .claude/skills/
• Detailed Setup: .claude/docs/setup.md
• Database Schema: .claude/docs/database-schema.md
• Key Patterns: .claude/docs/patterns.md

Support the Project:

• ⭐ Star the repo
• ☕ Buy Me a Coffee
• 💖 GitHub Sponsors

License

Licensed under the Apache 2.0 License - see LICENSE.

Contributions

Contributions are welcome! Please feel free to submit a Pull Request.

Contributors