RecyclerMap Application Guide

1. Introduction

• What: RecyclerMap maps verified plastic recyclers worldwide and helps brands quickly match their waste streams to the right partner.
• Why we built it: Recycling supply chains remain opaque; procurement teams often spend weeks cold-calling. RecyclerMap shortens that loop by blending curated recycler data, geospatial search, and transparent filters for plastic types, waste streams, and processing capabilities.
• How it works: A React/Vite frontend collects user filters, a Node/Express API queries a SQLite dataset, and results render on an interactive Leaflet map with rich recycler profiles.

2. App Features

• Landing experience: HeroSection exposes multi-select filters, location autocomplete (OpenStreetMap/Nominatim), and toggles for post-industrial vs. post-consumer capacity. Validation ensures a location and at least one plastic type before running a search.
• Search page:
  • SearchSidebar syncs filters with URL parameters, shows result counts, and opens a detailed recycler card with contact actions.
  • RecyclerMap plots recycler pins plus the user’s location, automatically adjusting viewports and applying offsets so markers stay visible beside the sidebar.
  • SearchContext keeps the form, URL, and TanStack Query state aligned so searches are reproducible by sharing links.
• API surface:
  • POST /api/search performs Zod validation, builds SQL EXISTS clauses against JSON columns, and calculates Haversine distance to sort by proximity.
  • GET /api/materials returns unique plastics/waste streams for populating dropdowns.
  • GET /api/recyclers/:id returns a fully typed recycler profile with parsed JSON fields.
• Database + seed pipeline: SQLite stores recycler rows with JSON columns for plastics and waste streams. WAL mode and schema bootstrapping keep the DB healthy. A seed.ts script ingests csv_data_set.csv so environments stay in sync.
• Scrapper module: The scrapper/ directory contains a Python Google Maps scraper (using googlemaps, pandas, etc.) plus a virtualenv. It enriches the recycler dataset before seeding—run it when you need to refresh coordinates or contact info, then rerun the backend seed script to push updates into SQLite.

3. Quickstart

Prerequisites

• Node 20+, npm (or pnpm/bun using the provided lockfiles)
• Python 3.12+ if you plan to run the scraper

Backend

cd backend
npm install
npm run seed   # loads backend/src/db/data/csv_data_set.csv into recyclers.db
npm run dev    # ts-node-dev hot server on http://localhost:4000

• Set DB_PATH when running outside dev so the API can locate the SQLite file (e.g., /var/data/recyclers.db).
• npm start serves the compiled build (npm run build first).

Frontend

cd frontend
npm install          # or pnpm install / bun install
npm run dev          # Vite on http://localhost:5173 (default)

• Configure VITE_API_URL in .env to point at your backend (http://localhost:4000/api in local dev).
• npm run build && npm run preview to inspect the production bundle.

Scrapper workflow (optional)

cd scrapper
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python google_maps_api.py  # exports refreshed recycler data

• Once new data is exported, copy it into backend/src/db/data/csv_data_set.csv (or the expected path) and rerun npm run seed so the API serves the updated dataset.

4. Support

• Issues/bugs: Open a Github Issue in this repository with reproduction steps, current environment, and logs.
• Questions: Reach the engineering team via email info@autocycle.dev.
• Operational alerts: The backend currently logs to stdout; aggregate via your hosting provider (e.g., Azure, Render) and set up monitors on /ping for uptime checks.

5. License

Copyright 2025 AUTOCYCLE

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.