AquaCheck NYC 💧

A full-stack web application that provides water quality scores for NYC ZIP codes using official NYC Open Data.

🌟 Features

Real NYC Data: Uses official NYC Open Data from distribution monitoring sites
178 NYC ZIP Codes: Covers all 5 boroughs (Manhattan, Brooklyn, Queens, Bronx, Staten Island)
0-100 Quality Score: Easy-to-understand score based on 5 key water quality metrics
Detailed Metrics: Turbidity, chlorine, fluoride, coliform, and E. coli measurements
Filter Recommendations: Personalized filtration suggestions based on your water quality
Confidence Indicators: Know how recent and reliable the data is

📊 Data Sources

Dataset	Source	Description
Water Quality	NYC Open Data bkwf-xfky	Distribution monitoring measurements
ZIP Boundaries	NYC Open Data pri4-ifjk	NYC MODZCTA boundaries

🏗️ Architecture

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│                 │      │                 │      │                 │
│  Next.js 16     │ ───► │  FastAPI        │ ───► │  SQLite         │
│  Frontend       │      │  Backend        │      │  Database       │
│  (Port 3000)    │      │  (Port 8000)    │      │                 │
│                 │      │                 │      │                 │
└─────────────────┘      └─────────────────┘      └─────────────────┘
        │                        │
        │                        ▼
        │               ┌─────────────────┐
        │               │  NYC Open Data  │
        │               │  (Socrata API)  │
        │               └─────────────────┘
        │
        ▼
┌─────────────────┐
│  User Browser   │
└─────────────────┘

🚀 Quick Start

Prerequisites

Node.js 18+ and npm
Python 3.10+
Git

Option 1: Development Mode

1. Clone the Repository

git clone https://github.com/ghostkush/Hackathon_02_27.git
cd Hackathon_02_27

2. Setup Backend

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run data pipeline (downloads NYC data and builds database)
python -m data_pipeline.ingest_sites
python -m data_pipeline.ingest_zips
python -m data_pipeline.ingest_water
python -m data_pipeline.build_zip_site_map
python -m data_pipeline.build_zip_summary

# Start backend server
uvicorn app.main:app --reload --port 8000

3. Setup Frontend (in a new terminal)

cd Hackathon_02_27

# Install dependencies
npm install

# Start development server
npm run dev

4. Open the App

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Docs: http://localhost:8000/docs

Option 2: Docker Compose (Recommended for Production)

# Build and start both services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

Access the app at http://localhost:3000

📁 Project Structure

Hackathon_02_27/
├── app/                      # Next.js app directory
│   ├── api/
│   │   └── water-quality/    # API route (proxies to backend)
│   ├── layout.tsx
│   └── page.tsx              # Main page
├── components/               # React components
│   ├── water-results.tsx     # Results display
│   ├── zip-search.tsx        # ZIP search input
│   ├── score-ring.tsx        # Score visualization
│   ├── contaminant-card.tsx  # Metric cards
│   └── ui/                   # UI primitives
├── backend/                  # Python FastAPI backend
│   ├── app/
│   │   ├── main.py           # FastAPI application
│   │   ├── config.py         # Configuration
│   │   ├── db.py             # Database helpers
│   │   ├── models.py         # Pydantic models
│   │   ├── parsing.py        # Value parsing
│   │   ├── mapping.py        # ZIP-site mapping
│   │   └── scoring.py        # Scoring engine
│   ├── data_pipeline/        # Data ingestion scripts
│   │   ├── ingest_sites.py
│   │   ├── ingest_zips.py
│   │   ├── ingest_water.py
│   │   ├── build_zip_site_map.py
│   │   └── build_zip_summary.py
│   ├── water.db              # SQLite database (generated)
│   ├── requirements.txt
│   ├── Dockerfile
│   └── README.md
├── docker-compose.yml        # Docker orchestration
├── Dockerfile                # Frontend Docker image
├── package.json
├── .env.local.example        # Environment template
└── README.md                 # This file

🔌 API Reference

GET /score

Get water quality score for an NYC ZIP code.

Request:

curl "http://localhost:8000/score?zip=10001"

Response:

{
  "zip": "10001",
  "score": 62,
  "confidence": "medium",
  "window": {
    "preferred_days": 30,
    "used_days": 180,
    "min_samples_30d": 10
  },
  "as_of": {
    "start": "2025-09-07",
    "end": "2025-12-28"
  },
  "sites_used": [
    {"sample_site": "33100", "distance_km": 3.12, "weight": 0.31}
  ],
  "metrics": {
    "turbidity": {"mean": 0.64, "min": 0.11, "max": 0.97, "n": 25},
    "residual_free_chlorine": {"mean": 0.70, "min": 0.45, "max": 0.87, "n": 25},
    "fluoride": {"mean": null, "min": null, "max": null, "n": 0},
    "coliform_mpn": {"mean": 0.5, "max": 0.5, "n": 25},
    "e_coli_mpn": {"mean": 0.5, "max": 0.5, "n": 25},
    "sample_count_total": 25
  },
  "recommendations": [
    "This score uses NYC distribution monitoring sites, not building plumbing."
  ],
  "notes": []
}

Other Endpoints

Endpoint	Description
`GET /health`	Health check with database stats
`GET /stats`	Overall data statistics
`GET /zips`	List all valid NYC ZIP codes
`GET /docs`	Interactive Swagger UI

⚙️ Configuration

Environment Variables

Frontend (.env.local)

BACKEND_URL=http://localhost:8000

Backend

Variable	Default	Description
`HOST`	`0.0.0.0`	Server host
`PORT`	`8000`	Server port
`CORS_ORIGINS`	`http://localhost:3000`	Allowed CORS origins (comma-separated)
`SOCRATA_APP_TOKEN`	``	NYC Open Data API token (optional, increases rate limits)

📈 Scoring Algorithm

Base Score: 100

Penalties are applied based on water quality metrics:

Condition	Penalty
E. coli max ≥ 1 MPN/100mL	-50
E. coli mean ≥ 0.5 MPN/100mL	-25
Coliform max ≥ 10 MPN/100mL	-20
Coliform mean ≥ 1 MPN/100mL	-10
Turbidity max ≥ 1.0 NTU	-15
Turbidity mean ≥ 0.5 NTU	-8
Chlorine mean < 0.2 mg/L	-8
Medium confidence (stale data)	-5
Low confidence (very stale data)	-12

Final score: 0-100 (clamped)

Confidence Levels

High: Data within 30 days, ≥30 samples
Medium: Data within 180 days, ≥10 samples
Low: Older data or fewer samples

🚢 Deployment

Vercel + Railway/Render

Frontend (Vercel):
- Connect GitHub repo to Vercel
- Set BACKEND_URL environment variable to your backend URL

Backend (Railway/Render):

# Railway
railway init
railway up

# Or Render
# Connect repo and set build command: pip install -r requirements.txt
# Start command: uvicorn app.main:app --host 0.0.0.0 --port $PORT

Docker Production

# Build images
docker-compose build

# Run with custom environment
CORS_ORIGINS=https://your-domain.com docker-compose up -d

🔄 Updating Data

To refresh the water quality data:

cd backend
source venv/bin/activate
python -m data_pipeline.ingest_water
python -m data_pipeline.build_zip_summary

This fetches the latest data from NYC Open Data and recomputes all scores.

🧪 Testing

Backend

cd backend
source venv/bin/activate

# Test API endpoints
curl http://localhost:8000/health
curl http://localhost:8000/score?zip=10001

Frontend

npm run build
npm run lint

📝 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

NYC Open Data for providing water quality monitoring data
NYC DEP (Department of Environmental Protection)
Hackathon_02_27 team

Built with ❤️ for NYC

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
app		app
backend		backend
components		components
hooks		hooks
lib		lib
public		public
styles		styles
.env.local.example		.env.local.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
components.json		components.json
docker-compose.yml		docker-compose.yml
next-env.d.ts		next-env.d.ts
next.config.mjs		next.config.mjs
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
requirements.txt		requirements.txt
start-dev.sh		start-dev.sh
test.ipynb		test.ipynb
tsconfig.json		tsconfig.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo

Folders and files

Latest commit

History

Repository files navigation

AquaCheck NYC 💧

🌟 Features

📊 Data Sources

🏗️ Architecture

🚀 Quick Start

Prerequisites

Option 1: Development Mode

1. Clone the Repository

2. Setup Backend

3. Setup Frontend (in a new terminal)

4. Open the App

Option 2: Docker Compose (Recommended for Production)

📁 Project Structure

🔌 API Reference

GET /score

Other Endpoints

⚙️ Configuration

Environment Variables

Frontend (.env.local)

Backend

📈 Scoring Algorithm

Base Score: 100

Confidence Levels

🚢 Deployment

Vercel + Railway/Render

Docker Production

🔄 Updating Data

🧪 Testing

Backend

Frontend

📝 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages