How bd2720/instant-map works
Project Type and Purpose
• This is a full-stack, serverless web application built on Next.js.
• Purpose: Allow end users to upload or paste lists of coordinates/addresses (CSV, XLSX, XML, JSON, GeoJSON), geocode them on demand, and render an interactive map with MapLibre + OpenFreeMap.
File Structure
• Top-level:
• next.config.ts, tsconfig.json, postcss.config.mjs, eslint.config.mjs – build & linting configuration for Next.js + TypeScript
• public/ – static assets (e.g., sample.geojson)
• src/app/ – Next.js “app” directory (pages, server-side routes, layout, global CSS)
• src/app/api/ – serverless functions (two routes: /api/geocode and /api/cron)
• src/app/redis/ – Redis connection & rate-limit logic (Upstash)
• src/app/lib/ – low-level helpers (convert, format, geocode, validate)
• src/app/hooks/ + src/app/components/ – React hooks & UI components for forms, map controls, file handling
• vercel.json – deployment settings + cron job schedule
README
• Confirms Tech Stack: Next.js, MapLibre, OpenFreeMap, Geoapify, Upstash Redis, Vercel.
• Features: multi-format file upload, forward geocoding, interactive map.
• Mentions “cron jobs”: likely for cache invalidation or cleaning old limits.
Main Components
a. Frontend Layer (Browser / Client)
• React pages & components in Next.js
• MapLibre map rendering with user-selected tile set from OpenFreeMap
• File upload & parsing (CSV, XLSX, XML, JSON, GeoJSON)
• Hooks for fetching sample data or pinned images
b. Serverless API Layer (Next.js API Routes)
• /api/geocode: accepts batch of addresses/coords → calls Geoapify Geocoding API → returns geojson
• /api/cron: scheduled job for maintenance (e.g., prune Redis counter, refresh sample data)
c. Data Store
• Upstash Redis: track per-IP or per-user API usage limits for Geoapify
d. External Services
• Geoapify Forward Geocoding API
• OpenFreeMap tile server
• Vercel platform: hosts Next.js serverless functions & static assets, schedules cron
e. Supporting Utilities
• src/app/lib modules (convert, format, validate) used by both frontend and backend
Relationships & Data Flow
1) User interacts with frontend → selects/upload file.
2) Frontend parsing library picks out addresses/coordinates → calls Next.js /api/geocode.
3) /api/geocode middleware:
• Checks rate limit in Upstash Redis (connect.ts + limits.ts).
• If under limit, uses lib/geocode.ts to call Geoapify API.
• Validates & formats results (lib/validate, lib/format).
4) /api/geocode returns geoJSON payload.
5) Frontend receives geoJSON → MapLibre component renders interactive map tiles from OpenFreeMap.
6) Separately, /api/cron runs on schedule (defined in vercel.json):
• Connects to Redis → resets counters or performs housekeeping.
7) public/sample.geojson can be fetched by frontend/useSampleData hook to show example.
Architectural Patterns & Design Principles
• Serverless micro-services style: each API route is its own function.
• Single Page Application (SPA) shells for UI with client-side hydration.
• Separation of concerns: lib/ for business logic, hooks/ for stateful logic, components/ for pure UI.
• Rate limiting via Redis to protect external API.
• Cron job orchestration via Vercel’s built-in scheduler.