From 1390bc21c6f24ad214e2be93e71e5ea7528d1426 Mon Sep 17 00:00:00 2001 From: Kirubakaran Date: Mon, 13 Oct 2025 14:08:02 +0530 Subject: [PATCH] Update README.md --- README.md | 278 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 162 insertions(+), 116 deletions(-) diff --git a/README.md b/README.md index 7be6159..f66c254 100644 --- a/README.md +++ b/README.md @@ -1,181 +1,227 @@ -Swap Station Real-Time Monitoring & Analytics Dashboard +# ⚡ 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 +- 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. - 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. +## 🚀 Key Features - 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. +### 🟢 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. - Data Export: Export detailed periodic and event logs as CSV files for offline analysis and record-keeping. +### ⚙️ Remote Control +- Securely send commands to swap stations: + - Open/close slots + - Enable/disable chargers + - Initiate swap cycles + - Trigger system reboot or maintenance actions - Station & User Management: Securely add, remove, and manage swap stations and user accounts. +### 📊 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 - Dockerized for Deployment: The entire application is containerized using Docker, Nginx, and Gunicorn, ensuring consistent and reliable deployment to any cloud environment. +### 📤 Data Export +- Export detailed periodic data and event logs as **CSV** for offline analysis or compliance archiving. -► Tech Stack +### 🧑‍💼 Station & User Management +- Role-based access control for administrators and operators. +- Add, update, or remove stations and users through a secure management panel. -Component - +### 🐳 Dockerized Deployment +- Fully containerized setup using **Docker**, **Nginx**, and **Gunicorn**. +- Ensures consistent, reproducible deployments to any cloud or on-prem environment. -Technology +--- -Backend - +## 🧠 Tech Stack -Python 3, Flask, Flask-SocketIO, SQLAlchemy, PostgreSQL +| 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) | -Frontend - +--- -HTML5, CSS3, JavaScript (ES6+), Tailwind CSS, Chart.js, Flatpickr.js +## 🧩 Local Installation & Setup Guide -Real-Time Engine - +Follow these steps to set up the application locally for development or testing. -MQTT (for station communication), WebSockets (for client communication) +### ✅ Prerequisites +Ensure the following are installed: -Deployment - +- **Python** ≥ 3.9 +- **Node.js** ≥ 16 and **npm** +- **PostgreSQL** (local instance running) +- **Git** -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 +### 1️⃣ Clone the Repository +```bash git clone cd SWAPSTATION_WEBAPP +``` -2. Backend Setup +### 2️⃣ Backend Setup +```bash +cd backend +``` +--- - Navigate to the backend directory: +### Create and Activate Virtual Environment - cd backend +macOS/Linux +```bash +python3 -m venv venv +source venv/bin/activate +``` - Create and activate a Python virtual environment: +--- +Windows +```bash +python -m venv venv +.\venv\Scripts\activate +``` +Install Dependencies +```bash +pip install -r requirements.txt +``` +--- - # For macOS/Linux - python3 -m venv venv - source venv/bin/activate +### Configure PostgreSQL - # For Windows - python -m venv venv - .\venv\Scripts\activate +1. Start your local PostgreSQL service. - Install Python dependencies: +2. Create a database and user. - pip install -r requirements.txt +```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 up the PostgreSQL Database: +### 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" +``` - Start your local PostgreSQL service. +--- +### 3️⃣ Frontend Setup +```bash +cd ../frontend +npm install +``` - 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; +### ▶️ Running the Application Locally - Configure Environment Variables: +Start Backend +```bash +cd backend +flask run --host=0.0.0.0 --port=5000 +``` +Backend API and WebSocket server → http://localhost:5000 - Create a .env file inside the backend/ directory. +### Start Frontend +- Open frontend/index.html with VS Code Live Server - Copy the contents of .env.example (if it exists) or use the template below, filling in your local database details. +- The app will be served at → http://127.0.0.1:5500 - # 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 +### ☁️ Deployment - Navigate to the frontend directory: +- This project is production-ready and designed for Docker-based deployment. - # From the project root - cd frontend +- For detailed step-by-step cloud deployment instructions (e.g., on AWS EC2), see: - Install Node.js dependencies: +📘 **DEPLOYMENT.md** - npm install +--- -► Running the Application Locally +### 🤝 Contributing - Start the Backend Server: +We welcome contributions! +To propose changes: - Make sure you are in the backend/ directory with your virtual environment activated. +1. Fork the repository. - Run the Flask application. The first time you run this, it will create the necessary database tables. +2. Create a new branch: - flask run --host=0.0.0.0 --port=5000 +```bash +git checkout -b feature/your-feature-name +``` - The backend API and WebSocket server is now running on http://localhost:5000. +3. Make and commit your changes with a clear message. - Serve the Frontend: +4. Push your branch: - The simplest way to serve the frontend for local development is using the Live Server extension in Visual Studio Code. +```bash +git push origin feature/your-feature-name +``` - Right-click on the frontend/index.html file and select "Open with Live Server". +5. Open a Pull Request to the main branch. - This will open the application in your browser, typically at http://127.0.0.1:5500. +Report issues or request features using the **GitHub Issues** tab. -► 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: +### ⚖️ License -➡️ DEPLOYMENT.md -► Contributing +Licensed under the MIT License. +See the **LICENSE** file for details. -Contributions are welcome! If you'd like to contribute to the project, please follow these steps: +--- - Fork the repository on GitHub. +### 🗂️ Project Structure - Create a new branch for your feature or bug fix (git checkout -b feature/your-feature-name). +```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 +``` - Make your changes and commit them with a clear, descriptive message. +--- - Push your branch to your fork (git push origin feature/your-feature-name). +### 🌐 Future Enhancements - Create a Pull Request back to the main repository. +- Integration with Grafana or Plotly Dash for richer analytics -Please report any bugs or suggest features using the GitHub Issues tab. -► License +- Mobile-friendly responsive layout -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 +- Integration with real swap station MQTT brokers for live hardware testing +- Role-based dashboards (admin/operator views) \ No newline at end of file