`cypressaward/README.md`

93 lines
# Cy Pres Award Platform

A comprehensive platform for tracking cy pres awards and connecting nonprofits with law firms specializing in class action lawsuits.

## Architecture Overview

### System Components

```
┌─────────────────────────────────────────────────────────────────┐
│                         Public Website                           │
│  (Featured Cases, Awards History, News, Law Firm Directory)      │
└────────────────────┬────────────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────────────┐
│                      API Gateway (NestJS)                        │
│         (Auth, Rate Limiting, Request Routing, RBAC)             │
└──┬──────────┬──────────┬──────────┬──────────┬─────────────────┘
   │          │          │          │          │
┌──▼───┐ ┌───▼───┐ ┌────▼────┐ ┌──▼───┐ ┌────▼────┐
│Portal│ │Portal │ │Matching │ │Email │ │Analytics│
│  NP  │ │ Firm  │ │ Engine  │ │Queue │ │   API   │
└──────┘ └───────┘ └─────────┘ └──────┘ └─────────┘
           │              │         │          │
┌──────────▼──────────────▼─────────▼──────────▼─────────────────┐
│              PostgreSQL + pgvector Database                      │
│  (Cases, Awards, Entities, Profiles, Matches, Audit)            │
└──────────────────────────┬──────────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────────┐
│                    Data Ingestion Pipeline                       │
├──────────────────────────────────────────────────────────────────┤
│ ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐ │
│ │  Crawler   │  │   Parser   │  │    NLP     │  │  Deduper   │ │
│ │(Playwright)│→ │   (ETL)    │→ │(Classifier)│→ │  (Hash)    │ │
│ └────────────┘  └────────────┘  └────────────┘  └────────────┘ │
└──────────────────────────────────────────────────────────────────┘
         ▲                                               │
         │                                               │
┌────────┴───────────┐                      ┌───────────▼──────────┐
│   Cron Scheduler   │                      │   OpenSearch/Redis   │
│ (Hourly/6-hour)    │                      │   (Cache & Search)   │
└────────────────────┘                      └──────────────────────┘
```

## Tech Stack

- **Backend**: TypeScript + NestJS
- **Database**: PostgreSQL 15+ with pgvector extension
- **Frontend**: Next.js 14 + Tailwind CSS + shadcn/ui
- **Crawler**: Playwright + Crawlee
- **Queue**: BullMQ + Redis
- **Search**: OpenSearch
- **NLP**: OpenAI API with local fallback (sentence-transformers)
- **Email**: AWS SES / Postmark
- **Hosting**: AWS ECS / Fly.io
- **Monitoring**: OpenTelemetry + Prometheus + Grafana

## Quick Start

```bash
# Install dependencies
cd backend && npm install
cd ../frontend && npm install
cd ../crawler && npm install

# Set up database
docker-compose up -d postgres redis opensearch

# Run migrations
cd backend && npm run migration:run

# Start services
npm run dev:backend
npm run dev:frontend
npm run dev:crawler
```

## Features

- Hourly web scraping for current cy pres cases
- 6-hour news aggregation
- Nonprofit registration and profile management
- Law firm directory and intake management
- AI-powered matching between nonprofits and cases
- Email automation and messaging system
- Public browsing of cases and awards
- Education lawsuit focus with pay-to-pay tracking
- Historical awards database (>$50,000)

## License

Copyright 2024. All rights reserved.