🚲 Velox 🚲

A full-stack application that provides AI-powered bicycle theft risk assessment for Toronto. The application combines historical theft data analysis with machine learning predictions to help cyclists make informed decisions about where to park their bikes.

Architecture

This is a monorepo containing:

• Frontend- Next.js application with interactive maps and risk visualization
• Backend- FastAPI service with machine learning model for theft prediction

Features

• Interactive Map- Click anywhere in Toronto to assess theft risk
• AI Risk Assessment- Machine learning model provides personalized risk predictions
• Historical Analysis- Analysis based on real Toronto Police theft data
• Personalized Risk- Factors in bike value, time of day, and lock type
• Modern UI- Clean, responsive interface with real-time updates

Prerequisites

• Docker and Docker Compose
• Node.js 18+ (for local development)
• Python 3.9+ (for local development)

Quick Start with Docker

1. Clone and navigate to the project:

   cd IBM-Z-Datathon

2. Start the application:

   docker-compose up --build

3. Access the application:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

The application will automatically load the bicycle theft data and ML model.

Local Development

Backend Setup

1. Navigate to backend directory:

   cd backend

2. Create 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 FastAPI server:

   uvicorn app.main:app --reload

Frontend Setup

1. Navigate to frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Create environment file:

   cp .env.local.example .env.local
   # Edit .env.local with your API URL if different from localhost:8000

4. Run the development server:

   npm run dev

API Endpoints

FastAPI Backend

• GET / - Health check
• GET /health - Detailed health status
• POST /predict - Risk prediction endpoint
• GET /model/info - Model information
• GET /docs - Swagger documentation

Example API Usage

curl -X POST "http://localhost:8000/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 43.6532,
    "longitude": -79.3832,
    "bike_price": 800,
    "time_of_day": 18,
    "day_of_week": "Friday",
    "lock_type": "u-lock",
    "location_type": "Street"
  }'

Project Structure

IBM-Z-Datathon/
├── backend/                  # FastAPI backend
│   ├── app/
│   │   ├── main.py          # FastAPI application
│   │   └── ml/              # ML models and utilities
│   │       ├── bike_theft_model.joblib
│   │       └── bike_prices_cache.pkl
│   ├── Dockerfile
│   └── requirements.txt
│
├── frontend/                 # Next.js frontend
│   ├── src/
│   │   ├── app/             # Next.js app directory
│   │   ├── components/      # React components
│   │   └── lib/             # API client and utilities
│   ├── public/              # Static assets
│   ├── Dockerfile
│   └── package.json
│
├── docker-compose.yml        # Docker orchestration
└── README.md

Data Sources

• Historical Theft Data: Toronto Police Service Public Safety Data Portal
• Geographic Data: OpenStreetMap via Leaflet
• Machine Learning: Pre-trained model based on historical patterns

Technology Stack

Frontend

• Next.js 15
• React 19
• TypeScript
• Tailwind CSS
• React Leaflet (for maps)
• Turf.js (for geospatial analysis)

Backend

• FastAPI
• Python 3.9+
• Scikit-learn
• Pandas
• Pydantic
• Uvicorn

Configuration

Environment Variables

Frontend (.env.local):

NEXT_PUBLIC_API_BASE_URL=http://localhost:8000

Backend:

# Set via Docker Compose or system environment
PYTHONPATH=/code

Development Tips

1. API Health: Check the API health indicator in the header
2. Hot Reload: Both frontend and backend support hot reloading in development
3. Model Updates: Replace the .joblib file in backend/app/ml/ to update the model
4. Data Updates: Replace the CSV file in frontend/public/ to update historical data

Troubleshooting

Common Issues

1. Port Conflicts: Ensure ports 3000 and 8000 are available
2. Model Loading: Check that bike_theft_model.joblib exists in backend/app/ml/
3. CORS Issues: Verify CORS settings in backend if accessing from different domains
4. Data Loading: Ensure bicycle-thefts.csv is in frontend/public/

Docker Issues

# Reset containers
docker-compose down
docker-compose up --build

# Check logs
docker-compose logs backend
docker-compose logs frontend

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test locally with Docker
5. Submit a pull request

License

This project is developed for the IBM Z Datathon hackathon.