# bd2720/instant-map architecture

> Architecture diagram of the GitHub repository bd2720/instant-map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bd2720/instant-map
- Repository: https://github.com/bd2720/instant-map

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Browser"
        UIshell["Frontend Main Page"]:::repo
        About["About Page"]:::repo
        Layout["Global Layout & Styles"]:::repo
        Header["Header & Navigation"]:::repo
        Sidebar["Sidebar (Controls & Forms)"]:::repo
        FileInput["File Input Component"]:::repo
        FileFormats["File Formats Selector"]:::repo
        FileInfo["File Info Display"]:::repo
        Geometries["Geometry Preview List"]:::repo
        MapComp["MapLibre Map Component"]:::repo
        MapControls["Map Controls Component"]:::repo
        Button["Reusable Button"]:::repo
        Radio["Reusable Radio"]:::repo
        UseSample["Sample Data Loader Hook"]:::repo
        UsePins["Pinned Images Hook"]:::repo
        SampleData["Static Sample GeoJSON"]:::data
    end

    subgraph "Serverless API (Next.js)"
        GeoAPI["Next.js /api/geocode"]:::repo
        CronAPI["Next.js /api/cron"]:::repo
        Connect["Redis Connect"]:::repo
        Limits["Redis Limits Logic"]:::repo
        Convert["Data Conversion Helper"]:::repo
        GeocodeLib["Geocoding Wrapper"]:::repo
        Validate["Input Validation Helper"]:::repo
        Format["Response Formatting Helper"]:::repo
    end

    Redis["Upstash Redis"]:::datastore
    Geoapify["Geoapify Geocoding API\n(HTTP REST)"]:::external
    OpenFree["OpenFreeMap Tile Server"]:::external
    Vercel["Vercel Platform"]:::external

    UIshell -->|uses| Header
    UIshell -->|uses| Sidebar
    Sidebar --> FileInput
    Sidebar --> FileFormats
    Sidebar --> FileInfo
    Sidebar --> Geometries
    UIshell -->|renders| MapComp
    UIshell -->|controls| MapControls
    FileInput -->|parses file| GeoAPI
    FileFormats -->|parses file| GeoAPI
    UseSample -->|fetches| SampleData
    UseSample -->|provides data to| UIshell
    UIshell -->|calls API| GeoAPI
    GeoAPI -->|checks rate limit| Connect
    Connect -->|queries| Limits
    Limits -->|stores/checks| Redis
    GeoAPI -->|calls| GeocodeLib
    GeocodeLib -->|HTTP request| Geoapify
    GeoAPI -->|validates| Validate
    GeoAPI -->|formats| Format
    GeoAPI -->|returns geoJSON| UIshell
    MapComp -->|tile requests| OpenFree
    Vercel -->|triggers cron| CronAPI
    CronAPI -->|connects to| Connect
    CronAPI -->|resets counters| Redis

    classDef repo fill:#D6E4FF,stroke:#333
    classDef external fill:#CCFFCC,stroke:#333
    classDef data fill:#FFF4E6,stroke:#333
    classDef datastore fill:#CCFFCC,stroke:#333

    click UIshell "https://github.com/bd2720/instant-map/blob/main/src/app/page.tsx"
    click About "https://github.com/bd2720/instant-map/blob/main/src/app/about/page.tsx"
    click Layout "https://github.com/bd2720/instant-map/blob/main/src/app/layout.tsx"
    click Layout "https://github.com/bd2720/instant-map/blob/main/src/app/globals.css"
    click Header "https://github.com/bd2720/instant-map/blob/main/src/app/components/header.tsx"
    click Sidebar "https://github.com/bd2720/instant-map/blob/main/src/app/components/sidebar.tsx"
    click FileInput "https://github.com/bd2720/instant-map/blob/main/src/app/components/file-input.tsx"
    click FileFormats "https://github.com/bd2720/instant-map/blob/main/src/app/components/file-formats.tsx"
    click FileInfo "https://github.com/bd2720/instant-map/blob/main/src/app/components/file-info.tsx"
    click Geometries "https://github.com/bd2720/instant-map/blob/main/src/app/components/geometries.tsx"
    click MapComp "https://github.com/bd2720/instant-map/blob/main/src/app/components/map.tsx"
    click MapControls "https://github.com/bd2720/instant-map/blob/main/src/app/components/map-controls.tsx"
    click Button "https://github.com/bd2720/instant-map/blob/main/src/app/components/button.tsx"
    click Radio "https://github.com/bd2720/instant-map/blob/main/src/app/components/radio.tsx"
    click UseSample "https://github.com/bd2720/instant-map/blob/main/src/app/hooks/useSampleData.tsx"
    click UsePins "https://github.com/bd2720/instant-map/blob/main/src/app/hooks/usePinImages.tsx"
    click GeoAPI "https://github.com/bd2720/instant-map/blob/main/src/app/api/geocode/route.ts"
    click CronAPI "https://github.com/bd2720/instant-map/blob/main/src/app/api/cron/route.ts"
    click Connect "https://github.com/bd2720/instant-map/blob/main/src/app/redis/connect.ts"
    click Limits "https://github.com/bd2720/instant-map/blob/main/src/app/redis/limits.ts"
    click Convert "https://github.com/bd2720/instant-map/blob/main/src/app/lib/convert.ts"
    click GeocodeLib "https://github.com/bd2720/instant-map/blob/main/src/app/lib/geocode.ts"
    click Validate "https://github.com/bd2720/instant-map/blob/main/src/app/lib/validate.ts"
    click Format "https://github.com/bd2720/instant-map/blob/main/src/app/lib/format.ts"
    click SampleData "https://github.com/bd2720/instant-map/blob/main/public/sample.geojson"
    click Vercel "https://github.com/bd2720/instant-map/blob/main/vercel.json"
```
