`QUICKSTART.md`

298 lines
# CyPresAwards - Quick Start Guide

Get up and running in 5 minutes!

## Prerequisites

- Node.js 18+ installed
- PostgreSQL 14+ installed and running
- Terminal access

## Step 1: Setup Database (2 minutes)

```bash
# Create database
createdb cypresawards

# Navigate to project
cd /root/WebsitesMisc/cypresawards

# Run schema
psql -d cypresawards -f database/schema.sql
```

Expected output: Multiple `CREATE TABLE`, `CREATE INDEX`, and `INSERT` statements

## Step 2: Configure Backend (1 minute)

```bash
cd backend

# Install dependencies
npm install

# Create .env file
cp .env.example .env

# Edit .env with your database password
nano .env  # or use your preferred editor
```

Minimum required in `.env`:
```env
DB_PASSWORD=your_postgres_password
```

## Step 3: Test the Scraper (1 minute)

```bash
# Run test scrape (3 sample organizations)
npm run scrape:test
```

Expected output:
```
Running in TEST mode with 3 sample URLs...

Scraping: https://bettzedek.org
✓ Successfully scraped: Bet Tzedek
  Categories: Legal Aid, Social Services
  Legal Topics: Consumer Protection, Housing

Progress: 3/3
=== Scraping Complete ===
Total: 3
Successful: 2-3
```

## Step 4: Start Backend API (30 seconds)

```bash
# In the backend directory
npm run dev
```

Expected output:
```
🚀 CyPresAwards API Server
📡 Server running on http://localhost:3000
🌍 Environment: development
```

Keep this terminal open!

## Step 5: Start Frontend (30 seconds)

Open a NEW terminal:

```bash
cd /root/WebsitesMisc/cypresawards/frontend

# Install dependencies
npm install

# Start dev server
npm start
```

Your browser should open automatically to `http://localhost:8080`

## Step 6: Explore the Application

You should now see:
- Search bar at the top
- Filter options (Legal Topics, Categories, State)
- Statistics cards showing database counts
- List of scraped organizations with logos, missions, and cy pres links

## Next Steps

### Add More Organizations

Edit `backend/src/utils/nonprofitUrls.js` and add URLs:

```javascript
const nonprofitUrls = [
  'https://your-nonprofit-here.org',
  // ... more URLs
];
```

Then run:
```bash
npm run scrape:test  # Test with first 3
# or
npm run scrape       # Scrape all (takes 2-4 hours)
```

### Customize the Database

Edit `database/schema.sql` to add:
- New legal topics
- New categories
- Custom fields

Then re-run:
```bash
psql -d cypresawards -f database/schema.sql
```

### Configure Scraper Behavior

In `backend/.env`:
```env
SCRAPER_DELAY_MS=3000        # Increase delay (more polite)
SCRAPER_MAX_CONCURRENT=3     # Reduce concurrency (slower but safer)
```

## Verify Everything Works

### Check Database

```bash
psql -d cypresawards -c "SELECT COUNT(*) FROM organizations;"
```

Should show the number of organizations scraped.

### Test API

```bash
curl http://localhost:3000/api/organizations | jq
```

Should return JSON with organizations.

### Check Frontend

Visit `http://localhost:8080` - you should see organizations displayed.

## Common Issues

### Issue: Database connection error

**Solution**: Check PostgreSQL is running:
```bash
pg_isready
```

If not running:
```bash
sudo service postgresql start  # Linux
brew services start postgresql # macOS
```

### Issue: Port already in use

**Solution**: Change ports in:
- Backend: Edit `backend/.env` → `PORT=3001`
- Frontend: Edit `frontend/package.json` → change port in scripts

### Issue: No organizations showing

**Solution**: Run the scraper first:
```bash
cd backend
npm run scrape:test
```

### Issue: npm install fails

**Solution**: Clear cache and retry:
```bash
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
```

## Production Deployment

See `README.md` for full deployment instructions including:
- Setting up production database
- Configuring environment variables
- Deploying to cloud providers
- SSL/TLS setup

## Architecture

```
Frontend (Port 8080)
    ↓ HTTP Requests
Backend API (Port 3000)
    ↓ SQL Queries
PostgreSQL Database
    ↑
Web Scraper (Batch)
```

## File Structure Reference

```
cypresawards/
├── backend/
│   ├── src/
│   │   ├── api/routes.js          # API endpoints
│   │   ├── models/Organization.js # Database queries
│   │   ├── scraper/main.js        # Scraper entry point
│   │   └── server.js              # Express server
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── index.html             # Main page
│   │   ├── app.js                 # Frontend logic
│   │   └── styles.css             # Styling
│   └── package.json
├── database/
│   └── schema.sql                 # Database schema
└── README.md                      # Full documentation
```

## Getting Help

1. Check `README.md` for detailed documentation
2. Check `docs/ARCHITECTURE.md` for system design
3. Check `docs/SCRAPING.md` for scraper details
4. Open an issue on GitHub

## Quick Commands Reference

```bash
# Database
createdb cypresawards
psql -d cypresawards -f database/schema.sql

# Backend
cd backend
npm install
npm run dev          # Start API server
npm run scrape:test  # Test scraper
npm run scrape       # Full scrape

# Frontend
cd frontend
npm install
npm start            # Start dev server

# Useful queries
psql -d cypresawards -c "SELECT * FROM organizations LIMIT 5;"
psql -d cypresawards -c "SELECT status, COUNT(*) FROM scraping_logs GROUP BY status;"
```

## Success Checklist

- [ ] Database created and schema loaded
- [ ] Backend dependencies installed
- [ ] .env file configured
- [ ] Test scrape completed successfully
- [ ] Backend API running on port 3000
- [ ] Frontend dependencies installed
- [ ] Frontend running on port 8080
- [ ] Organizations visible in browser
- [ ] Search and filters working

**Estimated total time: 5-10 minutes**

---

You're all set! Start exploring non-profit cy pres statements.