Swap Station Real-Time Monitoring & Analytics Dashboard

A full-stack web application designed for the real-time monitoring, control, and historical analysis of battery swap stations. This dashboard provides a comprehensive interface for administrators and operators to track station health, manage operations, and derive insights from performance data.
► Key Features

    Real-Time Dashboard: Live monitoring of station status, slot occupancy, battery vitals (Voltage, SoC, Temperature), and ongoing swap processes via WebSocket communication.

    Remote Control: Send commands directly to stations to open/close slots, enable/disable chargers, initiate swaps, and perform system reboots.

    Advanced Analytics: An interactive analytics page with customizable date ranges to visualize historical data, including swap activity, hourly distribution, abort reasons, and slot utilization heatmaps.

    Data Export: Export detailed periodic and event logs as CSV files for offline analysis and record-keeping.

    Station & User Management: Securely add, remove, and manage swap stations and user accounts.

    Dockerized for Deployment: The entire application is containerized using Docker, Nginx, and Gunicorn, ensuring consistent and reliable deployment to any cloud environment.

► Tech Stack

Component
	

Technology

Backend
	

Python 3, Flask, Flask-SocketIO, SQLAlchemy, PostgreSQL

Frontend
	

HTML5, CSS3, JavaScript (ES6+), Tailwind CSS, Chart.js, Flatpickr.js

Real-Time Engine
	

MQTT (for station communication), WebSockets (for client communication)

Deployment
	

Docker, Docker Compose, Nginx (Reverse Proxy), Gunicorn (WSGI Server)
► Local Installation & Setup Guide

These instructions will guide a developer in setting up the project on their local machine for development and testing.
Prerequisites

Ensure you have the following software installed on your system:

    Python (version 3.9+) & Pip

    Node.js (version 16+) & Npm

    PostgreSQL (a running local instance)

    Git

1. Clone the Repository

git clone <your-repository-url>
cd SWAPSTATION_WEBAPP

2. Backend Setup

    Navigate to the backend directory:

    cd backend

    Create and activate a Python virtual environment:

    # For macOS/Linux
    python3 -m venv venv
    source venv/bin/activate

    # For Windows
    python -m venv venv
    .\venv\Scripts\activate

    Install Python dependencies:

    pip install -r requirements.txt

    Set up the PostgreSQL Database:

        Start your local PostgreSQL service.

        Create a new user and a new database for the application. For example, using psql:

        CREATE DATABASE swap_station_db;
        CREATE USER swap_app_user WITH PASSWORD 'your_secure_password';
        ALTER DATABASE swap_station_db OWNER TO swap_app_user;

    Configure Environment Variables:

        Create a .env file inside the backend/ directory.

        Copy the contents of .env.example (if it exists) or use the template below, filling in your local database details.

        # backend/.env
        SECRET_KEY="a_random_secret_key_for_flask"
        DATABASE_URL="postgresql://swap_app_user:your_secure_password@localhost:5432/swap_station_db"
        CORS_ALLOWED_ORIGIN="[http://127.0.0.1:5500](http://127.0.0.1:5500)" # For VS Code Live Server

3. Frontend Setup

    Navigate to the frontend directory:

    # From the project root
    cd frontend

    Install Node.js dependencies:

    npm install

► Running the Application Locally

    Start the Backend Server:

        Make sure you are in the backend/ directory with your virtual environment activated.

        Run the Flask application. The first time you run this, it will create the necessary database tables.

        flask run --host=0.0.0.0 --port=5000

        The backend API and WebSocket server is now running on http://localhost:5000.

    Serve the Frontend:

        The simplest way to serve the frontend for local development is using the Live Server extension in Visual Studio Code.

        Right-click on the frontend/index.html file and select "Open with Live Server".

        This will open the application in your browser, typically at http://127.0.0.1:5500.

► Deployment

This application is designed for production deployment using Docker. For detailed, step-by-step instructions on how to deploy the application to an AWS server, please refer to the official guide:

➡️ DEPLOYMENT.md
► Contributing

Contributions are welcome! If you'd like to contribute to the project, please follow these steps:

    Fork the repository on GitHub.

    Create a new branch for your feature or bug fix (git checkout -b feature/your-feature-name).

    Make your changes and commit them with a clear, descriptive message.

    Push your branch to your fork (git push origin feature/your-feature-name).

    Create a Pull Request back to the main repository.

Please report any bugs or suggest features using the GitHub Issues tab.
► License

This project is licensed under the MIT License. See the LICENSE file for details.
► Project Structure

/SWAPSTATION_WEBAPP
|-- backend/            # Contains all Python/Flask backend source code
|   |-- core/
|   |-- models/
|   |-- proto/
|   |-- main.py         # Main Flask application entry point
|   |-- requirements.txt
|
|-- frontend/           # Contains all frontend assets
|   |-- js/             # JavaScript files
|   |-- css/            # CSS files
|   |-- assets/         # Images and other static assets
|   |-- *.html          # HTML pages
|
|-- .gitignore          # Specifies files to be ignored by Git
|-- Dockerfile          # Instructions to build the production Docker image
|-- docker-compose.yml  # Defines services for Docker Compose
|-- nginx.conf          # Nginx configuration for the reverse proxy
|-- DEPLOYMENT.md       # Detailed deployment guide
|-- README.md           # This file