Skip to content

README.md

Latest commit

 

History

History
275 lines (195 loc) · 7.99 KB

README.md

File metadata and controls

275 lines (195 loc) · 7.99 KB
Raw

CiteSight

Free, Open-Source Legal Citation Validation Tool

CiteSight is a free, self-hosted web application that helps legal professionals validate citations quickly and accurately using the CourtListener API. Users bring their own API keys - no SaaS subscription required. Built for solo practitioners, small law firms, and legal researchers who need reliable citation checking.

License: MIT TypeScript React

Features

  • Smart Citation Validation: Automatically validates legal citations against the CourtListener database
  • PDF Text Extraction: Upload PDFs and extract citations automatically via LlamaParse
  • Traffic Light System: Visual status indicators (Valid, Warning, Invalid)
  • PDF Report Generation: Export validation results as professional PDF reports
  • Self-Hosted: Bring your own API keys, no external accounts required
  • Responsive Design: Works seamlessly on desktop and mobile devices

Tech Stack

Frontend

  • React 18.3 - UI framework
  • TypeScript 5.8 - Type safety
  • Vite - Build tool and dev server
  • Tailwind CSS - Styling
  • shadcn/ui - Component library
  • React Router - Client-side routing
  • TanStack Query - Data fetching and caching

External Services

  • CourtListener API - Citation validation data source (free tier: 5000 requests/hour)
  • LlamaParse - Cloud PDF extraction service (optional, free tier: 1000 pages/day)
  • Cloudflare Turnstile - Bot protection (optional)

Quick Start

Prerequisites

  • Node.js 18+ and npm (or bun)
  • CourtListener API Key - Get one here (free, 5000 requests/hour)

Installation

  1. Clone the repository
git clone https://github.com/JaySmith502/cite-sight.git
cd cite-sight
  1. Install dependencies
npm install
  1. Set up environment variables

Copy .env.example to .env.local and fill in your credentials:

cp .env.example .env.local

Required variables:

# CourtListener API
VITE_COURTLISTENER_API_KEY=your_courtlistener_api_key

Optional variables:

# Cloudflare Turnstile (bot protection)
VITE_TURNSTILE_SITE_KEY=your_site_key
TURNSTILE_SECRET_KEY=your_secret_key

# LlamaParse (cloud PDF extraction)
# Get your key at: https://cloud.llamaindex.ai
VITE_LLAMA_CLOUD_API_KEY=your_llama_cloud_api_key
  1. Start the development server
npm run dev

The app will be available at http://localhost:5173

Docker Deployment

Quick Start with Docker

The easiest way to deploy CiteSight is with Docker:

  1. Clone the repository
git clone https://github.com/JaySmith502/cite-sight.git
cd cite-sight
  1. Create your environment file
cp .env.example .env

Edit .env and add your CourtListener API key:

VITE_COURTLISTENER_API_KEY=your_api_key_here
  1. Build and run
docker-compose up --build
  1. Access the application

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

Docker Configuration

Variable Required Default Description
VITE_COURTLISTENER_API_KEY Yes - Your CourtListener API key
VITE_BUILD_MODE No self-hosted Build mode (self-hosted or marketing)
VITE_LLAMA_CLOUD_API_KEY No - LlamaParse API key for PDF extraction
CITESIGHT_PORT No 3000 Port to expose on host

PDF Extraction (Optional)

CiteSight uses LlamaParse for PDF text extraction. To enable PDF uploads:

  1. Get a free API key at cloud.llamaindex.ai
  2. Add to your .env file: 
    VITE_LLAMA_CLOUD_API_KEY=your_api_key_here
  3. Rebuild the container: docker-compose up --build

Free tier limits: 1000 pages/day (sufficient for most individual users)

Without an API key, users can still paste text manually - the app gracefully degrades.

Rebuilding After Configuration Changes

Since VITE_ variables are baked at build time, you must rebuild after changing them:

docker-compose up --build

Production Considerations

  • The default image is ~50-80MB (nginx:alpine based)
  • Container runs as non-root user for security
  • Health check endpoint available at /health
  • Use restart: unless-stopped for automatic restarts

Documentation

API Rate Limiting

CourtListener API has rate limits (5000 requests/hour for free accounts). CiteSight implements:

  • Client-side rate limiting (55 requests/minute)
  • Exponential backoff on 429 errors
  • Request queuing for large documents

Development

Project Structure

cite-sight-check/
├── src/
│   ├── components/       # React components
│   ├── pages/           # Page components
│   ├── hooks/           # Custom React hooks
│   ├── services/        # API services
│   ├── utils/           # Utility functions
│   └── lib/             # Shared libraries
├── public/              # Static assets
└── dist/                # Build output

Available Scripts

npm run dev          # Start development server
npm run build        # Build for production
npm run build:dev    # Build with development mode
npm run preview      # Preview production build
npm run lint         # Run ESLint

Environment Modes

The app supports different build modes:

  • development - Full logging, development features
  • production - Optimized build, minimal logging

Alternative Deployment

Netlify / Static Hosting

CiteSight can be deployed to any static hosting platform (Netlify, Vercel, Cloudflare Pages):

  1. Set build command: npm run build
  2. Set publish directory: dist
  3. Add environment variables in the platform dashboard

The included netlify.toml configures SPA routing and security headers.

Security

Best Practices Implemented

  • No hardcoded credentials (all via environment variables)
  • Input validation with Zod schemas
  • Content Security Policy headers
  • HTTPS-only in production
  • Rate limiting on API calls

Security Considerations

  • Never commit .env.local or any file containing secrets
  • Rotate API keys regularly
  • Review netlify.toml CSP headers for your domain

See SECURITY.md for reporting vulnerabilities.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Development Workflow

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run linting (npm run lint)
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Acknowledgments

  • CourtListener - Free Law Project for providing the citation API
  • LlamaParse - LlamaIndex for the document parsing API
  • shadcn/ui - For the beautiful component library
  • Tailwind CSS - For the utility-first CSS framework

Support

Roadmap

  • Batch citation validation API
  • Citation format auto-correction
  • Bluebook vs. ALWD format detection
  • Integration with legal research platforms
  • Browser extension for in-page validation
  • Multi-language support

Disclaimer

CiteSight is a tool to assist with citation validation and should not be considered a substitute for professional legal research or verification. Always verify critical citations manually. This software is provided "as is" without warranty of any kind.

Built for the legal community