Guess The City

A web application that visualizes city road networks. A new city is featured every day.

Features

• City Road Visualization: Render detailed road networks for cities.
• Daily City: A new city featured every day.
• Random City: Discover a random city's road network.
• Interactive Map: Zoom and pan to explore the details.

Tech Stack

Backend

• Framework: FastAPI
• Language: Python
• Key Libraries: uvicorn, httpx, pydantic

Frontend

• Framework: React
• Build Tool: Vite
• Key Libraries: w-gl (WebGL rendering), d3-geo, pbf

Getting Started

Prerequisites

• Docker and Docker Compose (Recommended)
• OR Node.js and Python 3.8+ for manual setup

Installation (Docker - Recommended)

1. Clone the repository:

   git clone <repository-url>
   cd city-roads

2. Start the application:

   docker-compose up --build

3. Access the application:

   • Frontend: http://localhost:5173
   • Backend API Docs: http://localhost:8001/docs

Manual Installation

Backend

1. Navigate to the backend directory:

   cd backend

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Run the server:

   uvicorn app.main:app --reload --port 8000

Frontend

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Run the development server:

   npm run dev

Daily City Workflow

This project includes a GitHub Action workflow that automatically generates a new random city every day.

• Workflow: .github/workflows/daily_city.yml
• Script: scripts/generate_city.py
• Output: frontend/public/data/current_city.pbf (JSON format) and metadata.json

Static Deployment

The frontend can be deployed as a static site (e.g., GitHub Pages, Netlify) that consumes the pre-generated daily city data.

To enable static mode:

1. Set the environment variable VITE_USE_STATIC_DATA=true in your build environment or .env.local.
2. Build the frontend: npm run build.

In this mode, the app will load the city from /data/current_city.pbf instead of querying the backend API.

Project Structure

.
├── backend/            # FastAPI backend application
│   ├── app/            # Application source code
│   │   ├── api/        # API routers (roads, daily, random)
│   │   └── main.py     # Application entry point
│   └── requirements.txt
├── frontend/           # React frontend application
│   ├── src/            # Source code
│   └── package.json
├── scripts/            # Utility scripts
│   └── generate_city.py # Daily city generator
└── docker-compose.yaml # Docker orchestration

Inspired by: https://github.com/anvaka/city-roads