Neighbourhood Finder - Barcelona

Intelligent Barcelona neighbourhood recommendation system based on personalized preferences and socioeconomic data analysis, using Django and AWS services.

Description

Neighbourhood Finder is a web application that helps users find their ideal neighbourhood in Barcelona according to their preferences and needs. The system analyzes multiple socioeconomic and demographic parameters of each neighbourhood (safety, transport, services, commercial vitality, etc.) and generates personalized recommendations.

The project consists of two main applications:

• Public: Public interface for end users looking for neighbourhood recommendations
• DataLoad: Administrative panel for managing and loading neighbourhood and parameter data

Features

• AWS Cognito Authentication: Secure authentication system with support for registration, login and session management
• Personalized Recommendations: Scoring algorithm that weights different parameters according to user preferences
• Visual Recommendations: Image embeddings system with OpenAI for visual search of similar neighbourhoods
• Multiple Parameters: Analysis of safety, transport, health, education, commercial vitality, demographics, etc.
• Barcelona Data: Detailed information of all Barcelona neighbourhoods
• Data Management: Administrative panel to load and update neighbourhood and parameter data
• Responsive: Interface adapted for mobile and desktop devices
• Cloud Infrastructure: Deployed on AWS with high availability and scalability

Technologies

Backend

• Django 5.1.7: Main web framework
• Python 3.13: Programming language
• Gunicorn: WSGI server for production
• Boto3: AWS SDK for Python

Frontend

• HTML/CSS/JavaScript
• Bootstrap (responsive design)
• Django Templates

Database

• DynamoDB: Main database (NoSQL)
• SQLite: Local database for development

AWS Services

• Cognito (Authentication)
• DynamoDB (Database)
• S3 (Storage)
• EBS (Hosting)
• CloudWatch (Monitoring)
• SNS (Notifications)
• CloudFront (CDN, optional)

AI

• OpenAI API: Embeddings generation for visual recommendations
• Pillow: Image processing

Prerequisites

• Python 3.13+
• Docker and Docker Compose
• AWS account with access to the mentioned services
• OpenAI account (for image embeddings)
• Git

Installation

1. Clone the repository

git clone <repository-url>
cd neighborhood-recommender

2. Create virtual environments (local development)

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3. Configure environment variables

Create .env file for the public application:

# Django
DJANGO_SECRET_KEY=your-secret-key-here
DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=localhost:127.0.0.1
DJANGO_LOG_LEVEL=INFO

# App Mode
APP=Public

# AWS Credentials
AWS_REGION=eu-west-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_SESSION_TOKEN=your-session-token  # Optional

# AWS S3
AWS_S3_BUCKET_NAME=your-bucket-name
AWS_S3_LOGS_PREFIX=logs/
AWS_S3_PARAMETERS_PREFIX=parameters/

# DynamoDB Tables
DDB_TABLE_NEIGHBOURHOODS=NF_Neighbourhoods
DDB_TABLE_SCORES=NF_NeighbourhoodScores
DDB_TABLE_PARAMETERS=NF_Parameters
DDB_TABLE_IMAGE_EMBEDDINGS=NF_ImageEmbeddings

# AWS SNS
UPDATE_SNS_TOPIC=arn:aws:sns:region:account:topic

# CloudFront (Optional)
CLOUD_FRONT=False
AWS_STORAGE_BUCKET_NAME=your-storage-bucket
AWS_S3_CUSTOM_DOMAIN=your-cloudfront-domain.cloudfront.net

# OpenAI
OPENAI_API_KEY=your-openai-api-key

# AWS Cognito
COGNITO_USER_POOL_ID=your-user-pool-id
COGNITO_APP_CLIENT_ID=your-app-client-id
COGNITO_REGION=eu-west-1

Create admin.env file for the administrative application:

# Same variables as .env but with:
APP=DataLoad
DJANGO_ALLOWED_HOSTS=localhost:127.0.0.1

Configuration

Configure AWS DynamoDB

DynamoDB tables must have the following structure:

Table: NF_Neighbourhoods

• Partition Key: neighbourhood_name (String)
• Attributes: description, image_url, location, etc.

Table: NF_NeighbourhoodScores

• Partition Key: neighbourhood_name (String)
• Sort Key: parameter_name (String)
• Attributes: score (Number)

Table: NF_Parameters

• Partition Key: parameter_name (String)
• Attributes: description, weight, category, etc.

Table: NF_ImageEmbeddings

• Partition Key: embedding_id (String)
• Attributes: neighbourhood_name, embedding (List), image_url, etc.

Configure AWS Cognito

1. Create a User Pool in AWS Cognito
2. Create an App Client
3. Configure environment variables with the generated IDs
4. (Optional) Configure custom domains and OAuth

Configure AWS S3

1. Create an S3 bucket
2. Configure appropriate access policies
3. (Optional) Configure CloudFront for CDN
4. Upload neighbourhood images to the bucket

Usage

Local Development with Docker Compose

# Start both applications
docker-compose up --build

# Public application will be available at: http://localhost:8000
# Administrative application will be available at: http://localhost:8001

Local Development without Docker

# Activate virtual environment
source venv/bin/activate

# Apply migrations
python manage.py migrate

# Create superuser (optional)
python manage.py createsuperuser

# Start development server
python manage.py runserver

# For administrative application on another port:
python manage.py runserver 8001

Load Initial Data

1. Access the administrative panel (http://localhost:8001)
2. Authenticate with Cognito
3. Use data loading options:
   • Upload Parameters: Load parameter definitions from CSV
   • Upload Data: Load neighbourhood data from CSV files in /datasets/
   • Upload Image Embeddings: Generate embeddings for visual search

Processing scripts are available in datasets/scripts/:

• procesar_arboles.py
• procesar_seguridad.py
• procesar_transport.py
• And more...

Using the Public Application

1. Access http://localhost:8000
2. Register or log in with Cognito
3. Select parameter preferences (safety, transport, etc.)
4. Adjust weights according to personal importance
5. View neighbourhood recommendations ordered by score
6. (Optional) Use visual search by uploading an image

Deployment

Deployment on AWS Elastic Beanstalk

1. Prepare the code:

# Ensure all dependencies are in requirements.txt
pip freeze > requirements.txt

# Create .ebignore file (similar to .gitignore)
echo "venv/" > .ebignore
echo "*.pyc" >> .ebignore
echo "__pycache__/" >> .ebignore

2. Configure EB CLI:

# Install EB CLI
pip install awsebcli

# Initialize EB application
eb init -p docker neighborhood-recommender --region eu-west-1

# Create environments
eb create nf-public-env
eb create nf-admin-env

3. Configure environment variables in EB:

# Configure variables for public environment
eb setenv DJANGO_SECRET_KEY=xxx AWS_ACCESS_KEY_ID=xxx ... --environment nf-public-env

# Configure variables for administrative environment
eb setenv APP=DataLoad DJANGO_SECRET_KEY=xxx ... --environment nf-admin-env

4. Deploy:

# Deploy public application
eb deploy nf-public-env

# Deploy administrative application
eb deploy nf-admin-env

Application Load Balancer Configuration

Configure the ALB to route traffic:

• /admin/* → DataLoad instances (port 8001)
• /* → Public instances (port 8000)

Monitoring

• CloudWatch Logs: Logs are automatically sent to S3 and CloudWatch
• Metrics: Monitor DynamoDB usage, response latency, 5xx errors
• Alarms: Configure alarms for:
  • High DynamoDB usage
  • Application errors
  • Authentication issues

Datasets

The project includes processors for the following Barcelona datasets:

• Safety: Security cameras and surveillance data
• Transport: Metro stops, buses, and accessibility
• Health: Hospitals, pharmacies and health centers
• Demographics: Population, births, immigration
• Economy: Average income, commercial vitality
• Services: Places of worship, cultural exhibitions
• Environment: Trees, dog areas
• Accidents: Traffic accident data

Each dataset is processed through scripts in datasets/scripts/ that normalize and calculate scores per neighbourhood.

📄 License

MIT Licence

---

Neighbourhood Finder - Find your ideal neighbourhood in Barcelona