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

```bash
git clone <your-repository-url>
cd SWAPSTATION_WEBAPP
```

### 2️⃣ Backend Setup
```bash
cd backend
```
---

### Create and Activate Virtual Environment

macOS/Linux
```bash
python3 -m venv venv
source venv/bin/activate
```

---
Windows
```bash
python -m venv venv
.\venv\Scripts\activate
```
Install Dependencies
```bash
pip install -r requirements.txt
```
---

### Configure PostgreSQL

1. Start your local PostgreSQL service.

2. Create a database and user.

```bash
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:
```bash
# 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
```bash
cd ../frontend
npm install
```

---

### ▶️ Running the Application Locally

Start Backend
```bash
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:

```bash
git checkout -b feature/your-feature-name
```

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

4. Push your branch:

```bash
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

```bash
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)