227 lines
5.6 KiB
Markdown
227 lines
5.6 KiB
Markdown
# ⚡ 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) |