From cfd5a6d9ef8fdc0275656e56ba315e2f96c5cd75 Mon Sep 17 00:00:00 2001 From: Kirubakaran Date: Mon, 13 Oct 2025 13:25:02 +0530 Subject: [PATCH] fix: added the readme md file --- README.md | 272 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d7aecaa --- /dev/null +++ b/README.md @@ -0,0 +1,272 @@ +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 +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. + +► API Endpoints Overview + +The backend provides the following main RESTful API endpoints. All are prefixed with /api. + +Endpoint + + +Method + + +Description + +/login + + +POST + + +Authenticates a user. + +/users + + +POST + + +Adds a new user account. + +/stations + + +GET + + +Retrieves a list of all stations. + +/stations + + +POST + + +Adds a new station to the system. + +/stations/ + + +DELETE + + +Removes a station from the system. + +/stations/daily-stats + + +GET + + +Gets swap statistics for all stations (last 24h). + +/analytics + + +GET + + +Fetches detailed historical analytics data. + +/logs/recent/ + + +GET + + +Retrieves recent logs for a specific station. + +/logs/export + + +GET + + +Exports logs as a CSV file. + +/uptime/ + + +GET + + +Gets the live uptime percentage for a station. +► 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 +