feat: Setup web dashboard, api backend, developer scripts and guides

Author: Ankush Gupta

.gitignore

@@ -6,6 +6,13 @@ env/
 .venv/
 venv/
 
+# Environment files and secrets
+.env
+*.env
+.env.local
+.env.*
+
+
 # Build artifacts
 *.egg-info/
 dist/

DEVELOPMENT.md

@@ -0,0 +1,122 @@
+# Developer Guide: MapToPoster Setup & Architecture
+
+Welcome to the **MapToPoster** developer guide! This document explains how to set up the development environment, configure the codebase, and understand the application's core architecture.
+
+MapToPoster consists of a Python command-line map renderer, a FastAPI REST API (with an asynchronous sequential job queue), and a Next.js single-page web app.
+
+---
+
+## 🛠️ Prerequisites
+
+Ensure you have the following tools installed on your local machine:
+1. **Node.js** (v18.0.0 or higher) and `npm`
+2. **Python** (v3.11 or higher)
+3. **uv** (v0.1.0 or higher) — Astrals' ultra-fast Python package installer
+   * Install on macOS/Linux via Homebrew: `brew install uv`
+   * Install via curl: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+---
+
+## 🚀 Getting Started (Quick Setup)
+
+We have provided a custom setup script that configures virtual environments, installs Python and Node dependencies, and creates template configuration `.env` files automatically.
+
+1. **Clone & Navigate** to the repository.
+2. **Run the setup script**:
+   ```bash
+   ./setup_dev.sh
+   ```
+3. **Start the developer services**:
+   ```bash
+   ./start_dev.sh
+   ```
+
+`start_dev.sh` spins up both:
+* **FastAPI Backend**: [http://localhost:8000](http://localhost:8000) (Interactive Swagger Docs: `/api/swagger`)
+* **Next.js Frontend**: [http://localhost:3000](http://localhost:3000)
+
+Press `Ctrl+C` in the terminal to gracefully shut down both services.
+
+---
+
+## ⚙️ Environment Variables
+
+### FastAPI Backend (`web/backend/.env`)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ALLOWED_ORIGINS` | CORS allowed origins (comma-separated) | `http://localhost:3000` |
+| `CACHE_DIR` | Directory for geocoding & map features caching | `../../cache` |
+
+### Next.js Frontend (`web/frontend/.env.local`)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `BACKEND_URL` | Endpoint of the FastAPI backend server | `http://localhost:8000` |
+| `NEXT_PUBLIC_SITE_URL` | Canonical URL of the frontend website | `http://localhost:3000` |
+
+---
+
+## 📁 Repository Structure
+
+```text
+MapToPoster/
+├── create_map_poster.py    # Core map rendering engine (matplotlib + OSMnx)
+├── font_management.py      # Google Fonts loader and downloader
+├── setup_dev.sh            # One-click environment setup script
+├── start_dev.sh            # Concurrent developer services runner
+├── DEVELOPMENT.md          # This developer guide
+├── EXAMPLES.md             # API integration code samples
+├── pyproject.toml          # uv/python project metadata & requirements
+├── themes/                 # Curated theme JSON files
+├── fonts/                  # Custom fonts directory (Roboto + caches)
+├── posters/                # Outputs directory for generated map posters
+└── web/
+    ├── backend/
+    │   ├── main.py         # FastAPI REST application & Sequential Worker Queue
+    │   └── requirements.txt
+    └── frontend/
+        ├── package.json
+        ├── next.config.ts
+        └── src/
+            ├── app/        # Next.js Pages & Proxying (/api/[...proxy]/route.ts)
+            └── components/ # UI Elements (Header, Footer, ScrollReveal)
+```
+
+---
+
+## 🏗️ Architecture & Core Components
+
+```text
+┌────────────────────────┐
+│     Next.js Web UI     │ (localhost:3000)
+└────────────────────────┘
+            │
+            ▼ (Next.js API route proxying)
+┌────────────────────────┐
+│     FastAPI Server     │ (localhost:8000)
+└────────────────────────┘
+            │
+            ▼ (Job Submission)
+┌────────────────────────┐
+│ Sequential Worker Queue│ (Thread-safe background worker loop)
+└────────────────────────┘
+            │
+            ▼ (Calls)
+┌────────────────────────┐
+│  create_map_poster.py  │ (Generates maps with Nominatim + OSMnx)
+└────────────────────────┘
+```
+
+### 1. The Rendering Engine (`create_map_poster.py`)
+Fetches spatial features (streets, water bodies, park polygons) using the [OSMnx](https://github.com/gboeing/osmnx) library from OpenStreetMap APIs, scales road widths and highlights coordinates using [geopandas](https://geopandas.org/), and draws high-resolution posters with custom typography through [matplotlib](https://matplotlib.org/).
+
+### 2. FastAPI Async Queue Backend (`web/backend/main.py`)
+Matplotlib and geocoding resources contain global variables that are not thread-safe. To handle concurrent API requests safely, the backend:
+1. Receives requests via `/api/generate` and assigns a UUID (`job_id`).
+2. Appends the job request into an in-memory sequential queue (`_job_queue`).
+3. A background worker loop processes jobs one-by-one to avoid state corruption.
+4. Clients poll `/api/jobs/{job_id}` until status is `done`, returning the poster image encoded in base64.
+
+### 3. Next.js App Proxy (`web/frontend/src/app/api/[...proxy]/route.ts`)
+To prevent CORS preflight requests in production, Next.js uses an catch-all proxy route. Any requests to `/api/*` on port `3000` are automatically forwarded to `BACKEND_URL/api/*` on the server-side.

EXAMPLES.md

@@ -0,0 +1,183 @@
+# MapToPoster API Examples
+
+This document provides complete, copy-pasteable examples for programmatically generating city map posters using the MapToPoster REST API.
+
+* **Local Base URL**: `http://localhost:8000`
+* **Production Base URL**: `https://your-service.onrender.com` (Replace in examples if deploying to cloud)
+
+---
+
+## 1. Using cURL (Terminal)
+
+Because the API uses an asynchronous job polling pattern, generating a poster involves two steps: submitting the request and checking status until finished.
+
+### Step 1: Submit a generation request
+```bash
+curl -X POST http://localhost:8000/api/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "city": "Rome",
+    "country": "Italy",
+    "theme": "warm_beige",
+    "distance": 8000,
+    "width": 12,
+    "height": 16
+  }'
+```
+
+**Expected Response**:
+```json
+{
+  "job_id": "4b68e9e1-64d8-4f8b-a7a2-f8c6db24e392",
+  "status": "pending"
+}
+```
+
+### Step 2: Poll status using the `job_id`
+```bash
+curl http://localhost:8000/api/jobs/4b68e9e1-64d8-4f8b-a7a2-f8c6db24e392
+```
+
+**Expected Response (when processing)**:
+```json
+{
+  "job_id": "4b68e9e1-64d8-4f8b-a7a2-f8c6db24e392",
+  "status": "processing"
+}
+```
+
+**Expected Response (when complete)**:
+```json
+{
+  "job_id": "4b68e9e1-64d8-4f8b-a7a2-f8c6db24e392",
+  "status": "done",
+  "city": "Rome",
+  "country": "Italy",
+  "theme": "warm_beige",
+  "image_base64": "iVBORw0KGgoAAAANSUhEUg...",
+  "filename": "rome_warm_beige_22060525_120000.png",
+  "error": null,
+  "created_at": "2026-05-25T12:00:00.000",
+  "completed_at": "2026-05-25T12:01:15.000"
+}
+```
+
+---
+
+## 2. Using Python
+
+This complete Python script submits a request, polls the backend API until completion, decodes the resulting base64 image, and saves it to a local file.
+
+```python
+import base64
+import time
+import requests
+
+API_BASE = "http://localhost:8000/api"
+
+def generate_poster(city, country, theme="terracotta", distance=15000):
+    payload = {
+        "city": city,
+        "country": country,
+        "theme": theme,
+        "distance": distance,
+        "width": 12.0,
+        "height": 16.0
+    }
+    
+    # 1. Submit the generation job
+    print(f"Submitting job for {city}, {country} ({theme} theme)...")
+    res = requests.post(f"{API_BASE}/generate", json=payload)
+    res.raise_for_status()
+    job_data = res.json()
+    job_id = job_data["job_id"]
+    print(f"Job enqueued with ID: {job_id}")
+
+    # 2. Poll for completion
+    while True:
+        status_res = requests.get(f"{API_BASE}/jobs/{job_id}")
+        status_res.raise_for_status()
+        status_data = status_res.json()
+        status = status_data["status"]
+        
+        print(f"Current Job Status: {status}")
+        
+        if status == "done":
+            img_b64 = status_data["image_base64"]
+            filename = status_data.get("filename", f"{city.lower()}_poster.png")
+            
+            # Decode and write to disk
+            with open(filename, "wb") as f:
+                f.write(base64.b64decode(img_b64))
+            print(f"🎉 Success! Poster downloaded and saved to: {filename}")
+            break
+        elif status == "error":
+            print(f"❌ Generation failed. Error: {status_data.get('error')}")
+            break
+            
+        time.sleep(5)  # wait 5 seconds before polling again
+
+if __name__ == "__main__":
+    generate_poster("Monaco", "Monaco", theme="neon_cyberpunk", distance=3000)
+```
+
+---
+
+## 3. Using JavaScript / Node.js
+
+This example uses Node's native `fetch` API to query, poll, and write the generated base64 image data to a file.
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+
+const API_BASE = "http://localhost:8000/api";
+
+async function generatePoster(city, country, theme = "blueprint", distance = 10000) {
+  const payload = { city, country, theme, distance };
+
+  try {
+    // 1. Submit Job
+    console.log(`Submitting job for ${city}, ${country}...`);
+    const submitRes = await fetch(`${API_BASE}/generate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+    
+    if (!submitRes.ok) throw new Error(`Submission failed: ${submitRes.statusText}`);
+    const { job_id } = await submitRes.json();
+    console.log(`Job enqueued. ID: ${job_id}`);
+
+    // 2. Poll Status
+    const pollInterval = setInterval(async () => {
+      const pollRes = await fetch(`${API_BASE}/jobs/${job_id}`);
+      if (!pollRes.ok) {
+        console.error(`Polling failed, retrying...`);
+        return;
+      }
+      
+      const job = await pollRes.json();
+      console.log(`Status: ${job.status}`);
+
+      if (job.status === "done") {
+        clearInterval(pollInterval);
+        const buffer = Buffer.from(job.image_base64, 'base64');
+        const outputPath = path.join(__dirname, job.filename || `${city}_poster.png`);
+        
+        fs.writeFileSync(outputPath, buffer);
+        console.log(`🎉 Success! Poster saved to ${outputPath}`);
+      } else if (job.status === "error") {
+        clearInterval(pollInterval);
+        console.error(`❌ Generation error: ${job.error}`);
+      }
+    }, 4000);
+
+  } catch (error) {
+    console.error("API error:", error);
+  }
+}
+
+// Execute
+generatePoster("Venice", "Italy", "blueprint", 4000);
+```

README.md

@@ -1,6 +1,10 @@
 # City Map Poster Generator
 
-Generate beautiful, minimalist map posters for any city in the world.
+Generate beautiful, minimalist map posters for any city in the world via a CLI tool or the new local Web App!
+
+> [!NOTE]
+> This repository is a clone and web-extension of the original command-line interface map poster generator. 
+> All credit for the core map rendering engine, custom matplotlib styling, and themes goes to the original creator: [originalankur/maptoposter](https://github.com/originalankur/maptoposter).
 
 <img src="posters/singapore_neon_cyberpunk_20260118_153328.png" width="250">
 <img src="posters/dubai_midnight_blue_20260118_140807.png" width="250">
@@ -20,6 +24,23 @@ Generate beautiful, minimalist map posters for any city in the world.
 | UAE          | Dubai          | midnight_blue   | <img src="posters/dubai_midnight_blue_20260118_140807.png" width="250"> |
 | USA          | Seattle        | emerald         | <img src="posters/seattle_emerald_20260124_162244.png" width="250"> |
 
+## Web App & API Setup
+
+This project includes a web interface consisting of a Next.js frontend and a FastAPI backend. To run the web dashboard locally:
+
+1. **One-click developer environment setup**:
+   ```bash
+   ./setup_dev.sh
+   ```
+2. **Launch development services concurrently**:
+   ```bash
+   ./start_dev.sh
+   ```
+   * Open the dashboard at [http://localhost:3000](http://localhost:3000)
+   * Open interactive API documentation at [http://localhost:8000/api/swagger](http://localhost:8000/api/swagger)
+
+See [DEVELOPMENT.md](file:///Users/ankush/Documents/MapToPoster/maptoposter/DEVELOPMENT.md) for more details, and [EXAMPLES.md](file:///Users/ankush/Documents/MapToPoster/maptoposter/EXAMPLES.md) for API usage code snippets.
+
 ## Installation
 
 ### With uv (Recommended)

posters/ahmedabad_terracotta_20260516_191254.png

@@ -0,0 +1,15 @@
+services:
+  - type: web
+    name: maptoposter-api
+    env: python
+    region: oregon
+    plan: free
+    buildCommand: pip install -r web/backend/requirements.txt
+    startCommand: uvicorn web.backend.main:app --host 0.0.0.0 --port $PORT
+    envVars:
+      - key: PYTHON_VERSION
+        value: 3.11.0
+      - key: ALLOWED_ORIGINS
+        value: https://maptoposter.vercel.app,http://localhost:3000
+      - key: CACHE_DIR
+        value: /tmp/maptoposter_cache