Inocreal — Lost & Found

A public lost-and-found board. Someone reports an item they lost or found; anyone who recognises it sends a message; the platform relays it by email. Contact details are never published.

Live: https://lost-found-platform-six.vercel.app

• Node.js 20+ / Express 5
• TiDB Serverless (MySQL wire protocol) via mysql2
• Cloudinary for image storage, Multer for upload handling
• Nodemailer for the claim relay
• Vanilla JS frontend, installable as a PWA
• Google Maps where a key is configured, self-hosted Leaflet/OpenStreetMap otherwise
• Deployed on Vercel

---

How it works

  Reporter                     Inocreal                    Claimant
     |                            |                            |
     |-- POST /api/items -------->|                            |
     |   (photo -> Cloudinary)    |                            |
     |<-- confirmation email -----|                            |
     |    + private resolve link  |                            |
     |                            |<-- POST /:id/claim --------|
     |<-- "someone claimed it" ---|                            |
     |    + claimant's contact    |--- receipt --------------->|
     |                            |                            |
     |-- GET /:id/resolve?token ->|                            |
     |   item leaves the feed     |                            |

The reporter's contact details never appear in an API response or in the page. Only the reporter can close a report, using a capability token emailed to them — there are no user accounts.

API

Method	Path	Purpose
GET	/api/health	Liveness plus database reachability
GET	/api/config	Which map provider the page should use, and the browser key if there is one
GET	/api/items	Open items. Excludes contact_info and resolve_token
POST	/api/items	Report an item. multipart/form-data with an image field
POST	/api/items/:id/claim	Send a message to the reporter. JSON
GET	/api/items/:id/resolve?token=	Close a report. Link is emailed to the reporter

Rate limits: 5 reports and 10 claims per 15 minutes per IP, 120 reads per minute.

---

Local setup

git clone https://github.com/NIVYASHREE847/Lost_Found_Platform.git
cd Lost_Found_Platform
npm install
cp .env.example .env      # then fill it in — see below
npm run db:init           # creates the tables
npm run dev               # http://localhost:3000

Environment variables

Every value is read from the environment; nothing is hardcoded. .env is gitignored and must never be committed. .env.example lists all of these with placeholder values.

Variable	Required	Notes
DB_HOST	yes	TiDB Serverless gateway host
DB_PORT	yes	4000 for TiDB (not 3306)
DB_USER	yes	TiDB users look like xxxxxxxx.root
DB_PASSWORD	yes
DB_NAME	yes	e.g. lost_found_db
DB_SSL	no	TLS is on by default for any non-local host. Set false only for a local container
DB_POOL_SIZE	no	Default 2. See Serverless notes before raising it
GOOGLE_MAPS_API_KEY	no	Browser key. Unset means the map falls back to OpenStreetMap
GOOGLE_MAPS_MAP_ID	no	Cloud-styled map ID. Unset is fine — the dark palette lives in public/map.js
CLOUDINARY_CLOUD_NAME	yes
CLOUDINARY_API_KEY	yes
CLOUDINARY_API_SECRET	yes
EMAIL_USER	yes	Sending address
EMAIL_PASS	yes	Gmail App Password, 16 characters — not the account password
EMAIL_SERVICE	no	Default gmail
PUBLIC_BASE_URL	prod	Base URL for the resolve links in outbound email
CORS_ORIGIN	no	Lock the browser API to one origin. Unset allows any
IP_SALT	prod	Long random string, salts the stored hash of claimant IPs

If EMAIL_USER/EMAIL_PASS are absent the app still runs — it logs a warning and skips sending, and API responses report confirmation_email_sent: false.

Maps

The map is provider-agnostic. public/map.js asks /api/config which provider to use and loads only that one:

GOOGLE_MAPS_API_KEY	Provider	Notes
set	Google Maps JavaScript API	Loaded from maps.googleapis.com on demand
unset	Leaflet + OpenStreetMap	Served from public/vendor/leaflet, same origin

Both paths draw the same popups, the same loading shimmer and the same dark palette, so switching between them changes nothing the reader can see except the base map itself.

Leaflet is committed under public/vendor/ rather than pulled from a CDN. It used to load from unpkg.com, and whenever that request was slow or blocked the page showed an empty bordered box with nothing to say why. A same-origin file cannot fail that way.

Getting a browser key. Google Cloud console → APIs & Services → Credentials → Create API key. Then, on the key itself:

• Application restrictions: HTTP referrers, listing your domain and http://localhost:3000/*.
• API restrictions: Maps JavaScript API only.

The key is served to every visitor by /api/config, which is how the Maps JS API works — a browser key is public by design and the referrer restriction is what protects it. Never put a server key or an unrestricted key in this variable. server.js already allows Google's origins in the Content Security Policy; no further change is needed.

If the key is wrong, restricted to the wrong referrer, or has billing disabled, Google calls gm_authFailure. public/map.js catches that, rebuilds every live map on OpenStreetMap and tells the reader — instead of leaving a grey rectangle.

Database

TiDB Serverless is the only supported database. It speaks the MySQL protocol, has a free tier that needs no card, and tolerates the connection churn a serverless host produces.

This is the beginning of the README. Read the rest at the original. Read the full README ↗