🏛️ JudgeFinder

The legal transparency platform for judicial analytics and court intelligence

Visit JudgeFinder → | Documentation | Report Issue

---

🎯 Overview

JudgeFinder is a comprehensive judicial analytics and transparency platform that empowers attorneys, legal professionals, and organizations with AI-powered insights into judicial decisions, court data, and judicial behavior patterns.

Built with a modern tech stack (Next.js 15, React 18, TypeScript), JudgeFinder combines public court data from multiple authoritative sources with machine learning analysis to help legal professionals:

• Research judges across all US jurisdictions with detailed profiles and analytics
• Predict outcomes using AI-powered case analysis and historical patterns
• Detect bias with multi-dimensional analysis of judicial decision-making
• Track trends across courts, practice areas, and demographics
• Make informed decisions with confidence scoring and statistical validation

Key Statistics

• 1,800+ Judge profiles (California) expanding nationally to all 50 states
• 500+ Court pages with detailed jurisdiction information
• 40+ Database tables with normalized court data
• 175+ API endpoints for programmatic access
• 50,000+ Lines of production code with comprehensive test coverage

---

⭐ Features

🔍 Judicial Search & Discovery

• Full-text search across judges, courts, and jurisdictions
• Advanced filtering by practice area, court type, jurisdiction, and more
• Real-time search suggestions powered by semantic AI
• Pagination with CDN caching optimization
• SEO-friendly judge profiles with canonical URLs

Example: Search for "civil plaintiff favor rate > 70% in California" to find plaintiff-friendly judges

📊 Case Analytics Engine

Comprehensive analytics on judicial decision patterns:

• Civil Law: Plaintiff favor rates, contract enforcement, dismissal patterns
• Criminal Law: Conviction rates, sentencing patterns, plea agreement trends
• Family Law: Child custody outcomes, spousal support determinations
• Procedural: Motion approval rates, discovery disputes, pre-trial rulings

Each metric includes:

• Historical trend analysis
• Confidence scoring (0-100)
• Statistical sample size validation
• Data quality indicators and limitations

⚖️ Bias Detection & Analysis

Multi-dimensional bias analysis powered by AI:

• Case-type bias: Outcome variation across civil/criminal/family cases
• Temporal patterns: Decision consistency over time
• Demographic analysis: Outcome patterns by party characteristics
• Outcome normalization: Adjusted metrics accounting for case difficulty
• Confidence scoring: Statistical significance validation (-1.0 to 1.0 scale)

💬 AI-Powered Insights

• ChatGPT-style Q&A: Ask questions about judicial decisions in natural language
• Semantic search: Find similar cases and judges using embeddings
• Pattern recognition: Automatic identification of judicial tendencies
• Decision summaries: AI-generated case outcome explanations

💰 Advertising Platform (B2B)

Monetization channel for legal advertising:

• State Judge Listings: $500/month per state judge slot
• Federal Judge Listings: $500/month per federal judge
• Court Advertising: Premium court homepage placements at $5,000/month

Features:

• Real-time click and impression tracking
• Campaign performance analytics dashboard
• A/B testing capabilities
• Detailed ROI metrics

📋 Subscription System (B2C)

Three-tier pricing model for professional users:

Tier	Price	Features
Free	$0	Judge search, basic profiles, limited analytics
Professional	$29/mo or $290/yr	Advanced analytics, bias scores, AI chat
Enterprise	$299/mo or $2,990/yr	All features + API access + custom reports

Powered by Stripe with automatic billing, invoice management, and flexible upgrades/downgrades.

🔄 Data Synchronization

• Real-time data ingestion from CourtListener API (5,000 req/hour)
• UniCourt integration for structured case data
• Webhook support for push-based updates
• Bulk import capabilities for custom datasets
• Data validation and integrity checks with automatic rollback

🛡️ Admin Dashboard

Comprehensive administration tools:

• Judge verification and profile management
• Data audit and quality assurance
• Analytics cache warming and optimization
• Bulk import monitoring and status tracking
• Rate limiting and API quota management
• Stripe payment status and reconciliation
• Database health and performance metrics

---

🏗️ Architecture

Technology Stack

Frontend

• Framework: Next.js 15.5 (App Router, SSR, Static Generation)
• UI Library: React 18.3 with TypeScript 5.9
• Styling: Tailwind CSS 3.4 with custom theming
• UI Components: Radix UI primitives with Trellis design system
• Data Visualization: Recharts 3.3 + D3.js 7.9
• Animations: Framer Motion 12.23
• State Management: Zustand 5.0 (client), TanStack React Query 5.9 (server)
• Icons: Lucide React 0.539

Backend & Services

• Runtime: Node.js 20+ (LTS) or Node.js 22+
• Database: Supabase (PostgreSQL 16) with real-time subscriptions
• Authentication: Clerk OIDC with SSO support
• Caching: Upstash Redis for distributed caching
• Payment: Stripe for subscriptions + billing
• Hosting: Netlify with Edge Network CDN
• Monitoring: Sentry for error tracking and performance

AI & External Services

• Primary AI: Google Gemini 2.0 for analytics and insights
• Fallback AI: OpenAI GPT-4 Turbo
• Court Data: CourtListener API (primary), UniCourt (secondary)
• Bot Protection: Cloudflare Turnstile CAPTCHA
• Email: SendGrid transactional email
• Error Tracking: Sentry (client + server)

Development Tools

• Testing: Vitest (unit/integration), Playwright (E2E)
• Linting: ESLint with custom rules
• Formatting: Prettier with enforced style
• Git Hooks: Husky pre-commit validation
• Storybook: Component documentation and testing
• Bundle Analysis: Webpack bundle analyzer

---

🚀 Getting Started

Prerequisites

• Node.js: v20 or v22 LTS
• npm: v10 or higher (or Yarn, pnpm)
• Git: For version control
• Environment variables: API keys for Supabase, Clerk, Stripe, etc.

Installation

1. Clone the repository

   git clone https://github.com/anthropics/judge-finder.git
   cd JudgeFinder

2. Install dependencies

   npm install
   # or
   yarn install
   # or
   pnpm install

3. Configure environment variables

   cp .env.local.example .env.local

   Edit .env.local with your configuration:

   # Supabase
   NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
   SUPABASE_SERVICE_ROLE_KEY=your_service_key
   
   # Clerk Authentication
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key
   CLERK_SECRET_KEY=your_clerk_secret
   
   # Stripe Payments
   STRIPE_SECRET_KEY=your_stripe_secret
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_key
   STRIPE_WEBHOOK_SECRET=your_webhook_secret
   
   # External APIs
   COURTLISTENER_API_KEY=your_courtlistener_key
   GOOGLE_AI_API_KEY=your_gemini_key
   OPENAI_API_KEY=your_openai_key
   
   # Redis Caching
   UPSTASH_REDIS_REST_URL=your_redis_url
   UPSTASH_REDIS_REST_TOKEN=your_redis_token
   
   # Site Configuration
   NEXT_PUBLIC_SITE_URL=http://localhost:3000
   NODE_ENV=development

4. Start the development server

   npm run dev

   Open http://localhost:3000 in your browser.

Database Setup

1. Create Supabase project at supabase.com
2. Run migrations to create tables and functions:

   npm run migrate

3. Seed data (optional):

   npm run seed

4. Enable RLS for security:

   npm run security:enable-rls

Verification

Verify your setup is working:

# Run type checking
npm run type-check

# Run linting
npm run lint

# Run tests
npm test

# Start development server
npm run dev

---

📖 Documentation

Comprehensive documentation is available in the /docs directory:

Document	Purpose
docs/README.md	Documentation hub and overview
Getting Started	Detailed setup instructions
Architecture	System design and component overview
API Reference	Complete API endpoint documentation
Database Schema	Database structure and relationships
Testing Guide	Testing strategies and examples
Deployment	Netlify deployment process

---

🧪 Testing

JudgeFinder includes comprehensive test coverage with multiple testing strategies:

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test -- src/lib/analytics.test.ts

# Run unit tests only
npm run test:unit

# Run integration tests
npm run test:integration

# Run end-to-end tests
npm run test:e2e

# Generate coverage report
npm run test:coverage

Test Stack

• Unit & Integration: Vitest with jsdom
• E2E: Playwright (Chrome, Firefox, Safari)
• Mocking: MSW (Mock Service Worker) for API mocking
• Fixtures: Database fixtures for reproducible tests
• Performance: Lighthouse for performance budgets

---

🔨 Development

Available Scripts

# Development
npm run dev              # Start local dev server
npm run dev:turbo       # Dev with Turbo bundler

# Building
npm run build           # Production build
npm run build:analyze   # Analyze bundle size

# Testing
npm test                # Run all tests
npm run test:e2e        # Run E2E tests
npm run test:coverage   # Generate coverage

# Code Quality
npm run lint            # ESLint check
npm run format          # Prettier format
npm run type-check      # TypeScript check

# Database
npm run migrate         # Run migrations
npm run seed            # Seed database
npm run sync:all        # Sync all external data

# Admin Operations
npm run admin:grant-access      # Grant admin role
npm run analytics:warm-cache    # Warm analytics cache
npm run admin:bulk-import       # Start bulk import

# Validation
npm run validate:env    # Validate environment setup
npm run validate:all    # Full validation

Code Quality Standards

• ESLint: Configured for Next.js and React best practices
• Prettier: Enforced code formatting (2-space indentation)
• TypeScript: Strict mode enabled with no any types
• Pre-commit Hooks: Husky runs linting and formatting checks
• Performance Budgets: Webpack chunk size limits enforced

---

🚀 Deployment

Automatic Deployment

JudgeFinder uses Netlify for hosting with automatic deployments from the main branch.

Deployment process:

1. Push to main branch
2. GitHub webhook triggers Netlify build
3. Environment variables loaded from Netlify UI
4. Next.js production build (npm run build)
5. Build artifacts deployed to CDN
6. Automatic health checks verify deployment

See Deployment Guide for detailed instructions.

---

🤝 Contributing

We welcome contributions from the community! Please follow these guidelines:

Before You Start

1. Check open issues for existing work
2. Discuss major changes in an issue before starting development
3. Read documentation for detailed guidelines

Contribution Process

1. Fork the repository
2. Create feature branch: git checkout -b feature/your-feature
3. Follow code style guidelines (ESLint, Prettier)
4. Add tests for new functionality
5. Update documentation as needed
6. Submit pull request with clear description

Code Style

• TypeScript: Strict mode, no any types, proper typing
• React: Functional components with hooks
• Formatting: Prettier (run npm run format)
• Linting: ESLint (run npm run lint)

---

🔒 Security

Security Features

• Authentication: Clerk OIDC with SSO support
• Authorization: Role-based access control (RBAC)
• Data Encryption: AES-256 for sensitive fields
• API Security: Rate limiting, API key validation
• Bot Protection: Cloudflare Turnstile CAPTCHA
• SQL Injection Prevention: Parameterized queries via Supabase ORM
• XSS Protection: Content Security Policy (CSP) headers

Reporting Security Issues

Found a security vulnerability? Please email security@judgefinder.io instead of using public issues.

---

📞 Support

Getting Help

• Documentation: Comprehensive guides in /docs directory
• Issues: GitHub Issues
• Email: support@judgefinder.io

Resources

• JudgeFinder Website
• API Documentation
• Architecture Overview

---

📄 License

JudgeFinder is released under the MIT License.

---

🙏 Acknowledgments

• CourtListener - Judicial data source
• Supabase - Database infrastructure
• Netlify - Hosting and deployment
• Stripe - Payment processing

---

Visit JudgeFinder • Documentation • Report Issue