masalale/urban-mobility-explorer repository overview

⁠Urban Mobility Data Explorer

An enterprise-level full-stack application for analyzing and visualizing NYC Taxi Trip data patterns. This Docker container provides a complete, ready-to-run instance of the application with all dependencies, data processing, and database pre-configured.

⁠Quick Start

Pull and run the container:

docker pull masalale/urban-mobility-explorer:latest
docker run -p 5000:5000 masalale/urban-mobility-explorer:latest

Then open your browser to http://localhost:5000

⁠What's Included

This container includes:

• Python 3.12 runtime environment
• Flask 3.0.0 web framework with CORS support
• SQLite database with 1.4M+ NYC taxi trip records
• Data processing pipeline - Pre-processed and cleaned dataset
• Interactive dashboard - HTML/CSS/JavaScript frontend with Chart.js visualizations
• RESTful API - Multiple endpoints for data querying and filtering

⁠Features

• Automated Data Processing: Raw NYC taxi data is cleaned, validated, and enriched with derived features
• Normalized Database: 3NF schema with optimized indexes for fast queries
• Interactive Visualizations:
  • Trip duration distribution charts
  • Passenger count analysis
  • Time-of-day patterns
  • Geographic pickup/dropoff heatmaps
• Advanced Filtering: Filter by vendor, passenger count, duration, date, and location
• Custom Algorithm Implementation: Selection sort for data ordering (educational DSA demonstration)
• Responsive Design: Dark mode support and mobile-friendly interface

⁠Usage Options

⁠Option 1: Docker Run (Simple)

docker run -p 5000:5000 masalale/urban-mobility-explorer:latest

⁠Option 2: Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'

services:
  web:
    image: masalale/urban-mobility-explorer:latest
    ports:
      - "5000:5000"
    volumes:
      - ./backend/database:/app/backend/database
      - ./backend/logs:/app/backend/logs
    environment:
      - FLASK_ENV=production
    restart: unless-stopped

Then run:

docker-compose up

⁠Option 3: With Volume Persistence

To persist the database and logs across container restarts:

docker run -p 5000:5000 \
  -v $(pwd)/database:/app/backend/database \
  -v $(pwd)/logs:/app/backend/logs \
  masalale/urban-mobility-explorer:latest

⁠API Endpoints

The container exposes a RESTful API:

Example API call:

curl http://localhost:5000/api/trips/by_date?date=2016-03-14

⁠Technical Stack

• Backend: Python 3.12, Flask 3.0.0, Flask-CORS 4.0.0
• Database: SQLite 3 with normalized schema (3NF)
• Data Processing: Pandas 2.1.4, NumPy 1.26.2
• Frontend: HTML5, CSS3, JavaScript ES6+
• Visualization: Chart.js 4.4.0, jQuery 3.7.1

⁠Dataset

This application processes the NYC Taxi Trip Dataset containing:

• Pickup and dropoff timestamps
• GPS coordinates (latitude/longitude)
• Trip duration and calculated distance
• Passenger counts
• Vendor information
• Store-and-forward flags

Over 1.4 million trip records are cleaned, validated, and stored in the database.

⁠System Architecture

Three-tier architecture:

1. Frontend Layer: Interactive dashboard with Chart.js visualizations
2. Backend Layer: Flask API with business logic and data validation
3. Data Layer: SQLite database with optimized indexes

⁠Port Configuration

• Default Port: 5000
• Map to different host port: -p 8080:5000

⁠Environment Variables

• FLASK_APP: Set to backend/app.py
• FLASK_ENV: Set to production
• DOCKER_BUILD: Automatically set to 1 during build

⁠Container Size

• Image Size: ~1.87 GB
• Includes processed data and dependencies

⁠Educational Purpose

This project was developed as part of ALU Enterprise Web Development coursework, demonstrating:

• Data cleaning and ETL pipelines
• Database design and normalization
• RESTful API development
• Frontend visualization techniques
• Custom algorithm implementation (Selection Sort)

⁠Source Code

GitHub Repository: https://github.com/Masalale/urban_mobility_data_explorer⁠

Complete source code, documentation, and setup instructions available in the repository.

⁠License

Created for educational purposes as part of ALU Enterprise Web Development course.

⁠Support

For issues or questions:

• Open an issue on GitHub⁠
• Check the README⁠ for detailed documentation

⁠Contributors

• Fadhili Lumumba - Data Cleaning & Backend Development
• Clarence Chomba - Database Design & API Implementation
• Neville Iregi - Frontend Development & Visualization

Tags: urban-mobility, nyc-taxi, data-visualization, flask, python, sqlite, enterprise-web-development, data-analytics, full-stack, docker