SwapStation_WebApp/README.md

⚡ Swap Station Real-Time Monitoring & Analytics Dashboard

• A full-stack web application for real-time monitoring, control, and analytics of battery swap stations.
• It provides an end-to-end interface for administrators and operators to track station health, manage operations, and analyze performance trends — all from a unified dashboard.

---

🚀 Key Features

🟢 Real-Time Dashboard

• Live visualization of station and slot status.
• Displays battery vitals (Voltage, SoC, Temperature) and swap progress in real time.
• Powered by WebSocket communication for instant updates.

⚙️ Remote Control

• Securely send commands to swap stations:
  • Open/close slots
  • Enable/disable chargers
  • Initiate swap cycles
  • Trigger system reboot or maintenance actions

📊 Advanced Analytics

• Rich, interactive analytics with date-range filters.
• Visualizations include:
  • Swap frequency and activity trends
  • Hourly distribution charts
  • Abort-reason statistics
  • Slot utilization heatmaps

📤 Data Export

• Export detailed periodic data and event logs as CSV for offline analysis or compliance archiving.

🧑‍💼 Station & User Management

• Role-based access control for administrators and operators.
• Add, update, or remove stations and users through a secure management panel.

🐳 Dockerized Deployment

• Fully containerized setup using Docker, Nginx, and Gunicorn.
• Ensures consistent, reproducible deployments to any cloud or on-prem 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 (station communication), WebSockets (client communication)
Deployment	Docker, Docker Compose, Nginx (reverse proxy), Gunicorn (WSGI server)

---

🧩 Local Installation & Setup Guide

Follow these steps to set up the application locally for development or testing.

✅ Prerequisites

Ensure the following are installed:

• Python ≥ 3.9
• Node.js ≥ 16 and npm
• PostgreSQL (local instance running)
• Git

---

1️⃣ Clone the Repository

git clone <your-repository-url>
cd SWAPSTATION_WEBAPP

2️⃣ Backend Setup

cd backend

---

Create and Activate Virtual Environment

macOS/Linux

python3 -m venv venv
source venv/bin/activate

---

Windows

python -m venv venv
.\venv\Scripts\activate

Install Dependencies

pip install -r requirements.txt

---

Configure PostgreSQL

1. Start your local PostgreSQL service.

2. Create a database and user.

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;

---

Set Environment Variables

Create a .env file in the backend/ directory:

# 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"

---

3️⃣ Frontend Setup

cd ../frontend
npm install

---

▶️ Running the Application Locally

Start Backend

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

Backend API and WebSocket server → http://localhost:5000

Start Frontend

• Open frontend/index.html with VS Code Live Server

• The app will be served at → http://127.0.0.1:5500

---

☁️ Deployment

• This project is production-ready and designed for Docker-based deployment.

• For detailed step-by-step cloud deployment instructions (e.g., on AWS EC2), see:

📘 DEPLOYMENT.md

---

🤝 Contributing

We welcome contributions! To propose changes:

1. Fork the repository.

2. Create a new branch:

git checkout -b feature/your-feature-name

3. Make and commit your changes with a clear message.

4. Push your branch:

git push origin feature/your-feature-name

5. Open a Pull Request to the main branch.

Report issues or request features using the GitHub Issues tab.

---

⚖️ License

Licensed under the MIT License. See the LICENSE file for details.

---

🗂️ Project Structure

SWAPSTATION_WEBAPP/
├── backend/               # Flask backend
│   ├── core/              # Core app logic and services
│   ├── models/            # Database ORM models
│   ├── proto/             # Protobuf definitions (if applicable)
│   ├── main.py            # Flask entry point
│   └── requirements.txt
│
├── frontend/              # Frontend source files
│   ├── js/                # JavaScript logic
│   ├── css/               # Tailwind and custom styles
│   ├── assets/            # Images, icons, and static content
│   └── *.html             # UI pages
│
├── Dockerfile             # Build definition for backend container
├── docker-compose.yml     # Multi-service container orchestration
├── nginx.conf             # Reverse proxy configuration
├── DEPLOYMENT.md          # Cloud deployment instructions
├── .gitignore
└── README.md              # This file

---

🌐 Future Enhancements

• Integration with Grafana or Plotly Dash for richer analytics

• Mobile-friendly responsive layout

• Integration with real swap station MQTT brokers for live hardware testing

• Role-based dashboards (admin/operator views)