EV Spot - Electric Vehicle Charging Station Finder

Repository: https://github.com/shaanlabs/electra-grid-core.git

A comprehensive Django-based web application that helps EV users find and manage charging stations. Built with Django REST API and modern frontend technologies.

📋 Table of Contents

Features
Technology Stack
Installation
Database Models
API Endpoints
UI Components
Deployment
Testing
Mobile Features
Security Features
Contributing
License
Support
Future Enhancements
Performance

🚀 Features

Core Features

Interactive Map: Find charging stations near you using Leaflet.js
Real-time Availability: Check station availability and port status
User Authentication: Secure login/registration system
Charging Sessions: Start and stop charging sessions
Reviews & Ratings: Rate and review charging stations
Favorites: Save your preferred charging stations
Search & Filter: Filter stations by type, distance, and availability

Advanced Features

GPS Integration: Automatic location detection
Distance Calculation: Find stations within specified radius
Cost Tracking: Monitor charging costs and energy consumption
Mobile Responsive: Works perfectly on all devices
Real-time Updates: Live station status updates
Multi-language Support: Internationalization ready
Dark Mode: User preference support
Offline Capability: Basic functionality without internet

🛠️ Technology Stack

Backend

Django 4.2.7: Web framework with built-in admin interface
Django REST Framework 3.14.0: API development with browsable API
SQLite: Lightweight database (production-ready PostgreSQL support)
Django CORS Headers 4.3.1: Cross-origin resource sharing
Pillow 10.1.0: Image processing for profile pictures and station images
django-filter 23.5: Advanced filtering capabilities
python-decouple 3.8: Environment variable management

Frontend

Bootstrap 5: Modern, responsive UI framework
Font Awesome 6: Comprehensive icon library
Leaflet.js 1.9.4: Interactive maps with custom markers
Vanilla JavaScript: Modern ES6+ frontend logic
CSS3: Custom styling with CSS variables and animations

Development Tools

Python 3.8+: Programming language
Git: Version control
Virtual Environment: Isolated Python environment
Django Debug Toolbar: Development debugging (optional)

Production Ready

Gunicorn: WSGI HTTP Server
Nginx: Reverse proxy and static file serving
PostgreSQL: Production database (optional)
Redis: Caching and session storage (optional)
Docker: Containerization support

📦 Installation

Prerequisites

Python 3.8 or higher
pip (Python package installer)
Git (for cloning the repository)

Quick Start (Automated Setup)

# Clone the repository
git clone https://github.com/shaanlabs/electra-grid-core.git
cd electra-grid-core

# Run automated setup
python setup_project.py

Manual Setup Instructions

Clone the repository

git clone https://github.com/shaanlabs/electra-grid-core.git
cd electra-grid-core

Create virtual environment

python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

Install dependencies
```
pip install -r requirements.txt
```

Run migrations

python manage.py makemigrations
python manage.py migrate

Create superuser (optional)
```
python manage.py createsuperuser
```
Populate sample data (optional)
```
python manage.py populate_sample_data
```
Run the development server
```
python manage.py runserver
```
Access the application
- Main application: http://localhost:8000
- Admin panel: http://localhost:8000/admin
- API documentation: http://localhost:8000/api/

Testing the Setup

python test_project.py

Sample Data

The application comes with pre-populated sample data including:

5 Sample Users: Test accounts with different vehicle types
8 Charging Stations: Various locations with different charging types
Sample Reviews: User ratings and comments
Sample Sessions: Charging session history

🗄️ Database Models

ChargingStation

- name: CharField (Station name)
- address: TextField (Full address)
- latitude: DecimalField (GPS latitude)
- longitude: DecimalField (GPS longitude)
- charging_type: CharField (slow/fast/super)
- power_output: IntegerField (kW)
- price_per_kwh: DecimalField (Cost per kWh)
- status: CharField (active/inactive/maintenance)
- total_ports: IntegerField (Total charging ports)
- available_ports: IntegerField (Available ports)
- image: ImageField (Station image)
- description: TextField (Station description)
- amenities: TextField (Available amenities)

ChargingSession

- user: ForeignKey (User reference)
- station: ForeignKey (Station reference)
- start_time: DateTimeField (Session start)
- end_time: DateTimeField (Session end)
- energy_consumed: DecimalField (kWh consumed)
- total_cost: DecimalField (Total cost)
- status: CharField (active/completed/cancelled)

Review

- user: ForeignKey (User reference)
- station: ForeignKey (Station reference)
- rating: IntegerField (1-5 stars)
- comment: TextField (Review text)
- created_at: DateTimeField (Review timestamp)

CustomUser (Extended Django User)

- username: CharField (Unique username)
- email: EmailField (Unique email)
- first_name: CharField (First name)
- last_name: CharField (Last name)
- phone_number: CharField (Contact number)
- vehicle_type: CharField (EV type)
- profile_picture: ImageField (User avatar)

🔌 API Endpoints

Authentication Endpoints

POST /api/users/register/     # User registration
POST /api/users/login/        # User login
POST /api/users/logout/       # User logout
GET  /api/users/profile/      # Get user profile
PUT  /api/users/profile/      # Update user profile

Charging Station Endpoints

GET    /api/stations/                    # List all stations
GET    /api/stations/{id}/               # Get station details
POST   /api/stations/nearby/             # Find nearby stations
POST   /api/stations/{id}/start_charging/ # Start charging session
POST   /api/stations/{id}/stop_charging/  # Stop charging session

Session & Review Endpoints

GET  /api/sessions/          # User's charging sessions
GET  /api/reviews/           # Station reviews
POST /api/reviews/           # Create review
GET  /api/favorites/         # User's favorite stations
POST /api/favorites/         # Add station to favorites

API Response Format

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Success message",
  "timestamp": "2024-01-01T00:00:00Z"
}

🎨 UI Components

Hero Section

Gradient Background: Eye-catching design with EV-themed colors
Call-to-Action Buttons: "Find Stations" and "Learn More"
Responsive Design: Adapts to all screen sizes
Animation Effects: Smooth transitions and hover effects

Interactive Map

Leaflet.js Integration: Open-source mapping library
Custom Markers: Different icons for station types
Popup Information: Station details on marker click
User Location: GPS-based location detection
Cluster Markers: Group nearby stations for better UX

Search Interface

Radius Slider: 1-50km range selection
Charging Type Filters: Slow/Fast/Super charging options
Real-time Results: Instant search results
Advanced Filters: Price, availability, amenities

Station Cards

Information Display: Name, address, type, price
Availability Indicators: Visual status indicators
Quick Actions: Start charging, add to favorites
Rating Display: Star ratings with review count

User Dashboard

Profile Management: Edit personal information
Session History: Past charging sessions
Favorite Stations: Saved station list
Statistics: Usage analytics and trends

🚀 Deployment

Production Environment Setup

Environment Variables

export DEBUG=False
export SECRET_KEY='your-secure-secret-key'
export ALLOWED_HOSTS='your-domain.com,www.your-domain.com'
export DATABASE_URL='postgresql://user:pass@localhost/dbname'
export STATIC_ROOT='/path/to/static/files'
export MEDIA_ROOT='/path/to/media/files'

Database Setup (PostgreSQL)

# Install PostgreSQL adapter
pip install psycopg2-binary

# Update settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'evspot_db',
        'USER': 'evspot_user',
        'PASSWORD': 'secure_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

Static Files Collection

python manage.py collectstatic --noinput

Web Server Configuration

# Install Gunicorn
pip install gunicorn

# Run with Gunicorn
gunicorn evspot.wsgi:application --bind 0.0.0.0:8000

Docker Deployment

# Dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
RUN python manage.py collectstatic --noinput

EXPOSE 8000
CMD ["gunicorn", "evspot.wsgi:application", "--bind", "0.0.0.0:8000"]

# Build and run
docker build -t ev-spot .
docker run -p 8000:8000 ev-spot

Nginx Configuration

server {
    listen 80;
    server_name your-domain.com;

    location /static/ {
        alias /path/to/staticfiles/;
    }

    location /media/ {
        alias /path/to/media/;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

🧪 Testing

Automated Testing

# Run all tests
python manage.py test

# Run specific app tests
python manage.py test users
python manage.py test stations

# Run with coverage
coverage run --source='.' manage.py test
coverage report

API Testing

# Using curl
curl -X GET http://localhost:8000/api/stations/
curl -X POST http://localhost:8000/api/users/register/ \
  -H "Content-Type: application/json" \
  -d '{"username":"test","email":"[email protected]","password":"testpass123"}'

# Using Django REST Framework browsable API
# Visit http://localhost:8000/api/stations/ in browser

Manual Testing Checklist

📱 Mobile Features

Responsive Design

Mobile-First Approach: Designed for mobile devices first
Touch-Friendly Interface: Optimized for touch interactions
Swipe Gestures: Intuitive navigation gestures
Offline Capability: Basic functionality without internet

GPS Integration

Automatic Location Detection: Uses device GPS
Location Permissions: Handles permission requests
Fallback Location: IP-based location if GPS unavailable
Location History: Remembers user's last location

Performance Optimization

Lazy Loading: Images and content load on demand
Caching: Browser and API response caching
Compression: Optimized assets for faster loading
Progressive Web App: PWA capabilities for app-like experience

🔒 Security Features

Authentication & Authorization

CSRF Protection: Built-in Django CSRF tokens
Session Management: Secure session handling
Password Validation: Strong password requirements
Account Lockout: Protection against brute force attacks

Data Protection

Input Validation: Server-side validation for all inputs
SQL Injection Protection: Django ORM protection
XSS Protection: Template auto-escaping
HTTPS Enforcement: Secure communication in production

API Security

Rate Limiting: API request rate limiting
Token Authentication: JWT token support (optional)
CORS Configuration: Proper cross-origin settings
Request Validation: Comprehensive input validation

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository

git clone https://github.com/shaanlabs/electra-grid-core.git

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
- Follow PEP 8 style guidelines
- Add tests for new features
- Update documentation

Test your changes

python manage.py test
python test_project.py

Submit a pull request
- Provide clear description of changes
- Include screenshots if UI changes
- Reference any related issues

Development Guidelines

Code Style: Follow PEP 8 and Django conventions
Documentation: Update README and docstrings
Testing: Maintain test coverage above 80%
Commits: Use conventional commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2024 EV Spot

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🆘 Support

Getting Help

GitHub Issues: Create an issue
Documentation: Check the Wiki
Email Support: [email protected]
Community Forum: Join our community

Common Issues

Installation Problems: Check Python version and virtual environment
Database Issues: Ensure migrations are applied correctly
Static Files: Run collectstatic in production
API Errors: Check CORS settings and authentication

🔮 Future Enhancements

Planned Features

Payment Integration: Stripe/PayPal payment processing
Push Notifications: Real-time alerts and updates
Social Features: User communities and sharing
Analytics Dashboard: Advanced usage statistics
IoT Integration: Real-time station monitoring
Multi-language Support: Internationalization (i18n)

Technical Improvements

GraphQL API: Alternative to REST API
Microservices Architecture: Scalable service separation
Machine Learning: Predictive availability and pricing
Blockchain Integration: Decentralized payment system
Real-time WebSocket: Live updates and notifications

Mobile App

React Native App: Cross-platform mobile application
Offline Sync: Data synchronization when online
Push Notifications: Native mobile notifications
Biometric Authentication: Fingerprint/Face ID login

📊 Performance

Current Metrics

Page Load Time: < 3 seconds (average)
API Response Time: < 500ms (95th percentile)
Database Queries: Optimized with select_related/prefetch_related
Memory Usage: < 100MB (typical deployment)

Optimization Strategies

Database Indexing: Optimized queries with proper indexes
Caching: Redis integration for session and query caching
CDN: Static file delivery through CDN
Image Optimization: Compressed and responsive images
Code Splitting: Lazy loading of JavaScript modules

Monitoring

Application Monitoring: Django Debug Toolbar integration
Error Tracking: Sentry integration for error monitoring
Performance Metrics: Custom performance tracking
Uptime Monitoring: Service availability monitoring

🎯 Project Goals

EV Spot aims to revolutionize the EV charging experience by providing:

Accessibility: Easy-to-use interface for all users
Reliability: Accurate and up-to-date station information
Efficiency: Optimized routing and charging planning
Community: User-driven improvements and feedback
Sustainability: Supporting the transition to electric vehicles

Making EV charging accessible and convenient for everyone! ⚡🚗

⭐ Star this repository if you find it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
evspot		evspot
static		static
stations		stations
templates		templates
users		users
.gitignore		.gitignore
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
manage.py		manage.py
requirements.txt		requirements.txt
setup.py		setup.py
setup_project.py		setup_project.py
test_project.py		test_project.py

License

shaanlabs/electra-grid-core

Folders and files

Latest commit

History

Repository files navigation