Commit inicial: Projeto YuClusters

README.md

@@ -0,0 +1,67 @@
+# YuClusters Local 📊
+
+YuClusters Local is a professional footprint chart and volumetric cluster analyzer integrated directly with your local **MetaTrader 5 (MT5)** terminal.
+
+## Key Features
+
+- **Real-Time Footprint Charting**: Ticks polled at ~100ms intervals and visualised dynamically using an optimized HTML5 Canvas element.
+- **Diagonal Imbalances Detection**: Identifies aggressive buying or selling imbalances ($R \ge 3.0$).
+- **Stacked Imbalances Highlights**: Dynamically spots 3+ consecutive imbalances in the same direction.
+- **POC Highlight**: Identifies and highlights the highest volume nodes within each cluster using a gold border.
+- **Interactive Drag & Pan UI**: Fully-featured HTML5 Canvas dashboard with drag-to-scroll horizontal/vertical panning and zoom adjustment.
+
+---
+
+## Installation & Setup
+
+### 1. Prerequisites
+- **Windows OS** (required by MetaTrader 5 API)
+- **MetaTrader 5 Terminal** running locally and logged into your broker account
+- **Python 3.11+** installed and added to PATH
+- **Node.js 18+** installed
+
+### 2. Backend Installation
+
+1. From the project root, install Python dependencies:
+   ```powershell
+   pip install -r requirements.txt
+   ```
+2. Set your environment configurations in `config/settings.py` or export them as environment variables (e.g. `MT5_LOGIN`, `MT5_PASSWORD`, `MT5_SERVER`).
+
+### 3. Frontend Installation
+
+1. Navigate to the `frontend/` folder:
+   ```powershell
+   cd frontend
+   ```
+2. Install npm packages:
+   ```powershell
+   npm install
+   ```
+
+---
+
+## Execution Guide
+
+### 1. Run the Backend Server
+Start the FastAPI server (this will automatically launch the MetaTrader 5 polling collector):
+```powershell
+python backend/server.py
+```
+
+### 2. Run the React Frontend
+Start the Vite development server:
+```powershell
+cd frontend
+npm run dev
+```
+Open [http://localhost:3000](http://localhost:3000) in your web browser.
+
+---
+
+## Technical Calculations (from SKILL.md)
+
+1. **Diagonal Buy Imbalance**: `ask_vol[i] >= R * bid_vol[i-1]` (compares with price level below)
+2. **Diagonal Sell Imbalance**: `bid_vol[i] >= R * ask_vol[i+1]` (compares with price level above)
+3. **POC (Point of Control)**: Price level with the highest total volume (`ask_vol + bid_vol`) inside a cluster. If volumes tie, the highest price wins.
+4. **Stacked Imbalance Zone**: A vertical zone spanning 3 or more consecutive levels with the same imbalance direction.