From 242c7fb25ae53d131cc092e31fd0506f229246a4 Mon Sep 17 00:00:00 2001 From: mxnticek Date: Sat, 5 Jul 2025 20:32:55 +0200 Subject: [PATCH] Add readme.md --- readme.md | 275 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 readme.md diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..314bb79 --- /dev/null +++ b/readme.md @@ -0,0 +1,275 @@ +# UrNetwork Stats Dashboard - Refactored + + +Hits - [demo](http://38.242.156.120:90) | [![Hits](https://hits.sh/38.242.156.120:90.svg)](https://hits.sh/38.242.156.120:90/) + +Hits - [repo](https://forgejo.plainrock127.xyz/mxnticek/UrNetwork-Stats-Dashboard-remade) | [![Hits](https://hits.sh/forgejo.plainrock127.xyz/mxnticek/UrNetwork-Stats-Dashboard-remade.svg)](https://hits.sh/forgejo.plainrock127.xyz/mxnticek/UrNetwork-Stats-Dashboard-remade/) + + +----- + +## 🇬🇧 English + +### About The Project + +This project is a significantly enhanced and refactored version of the original [UrNetwork Stats Dashboard](https://github.com/techroy23/UrNetwork-Stats-Dashboard). The application is designed to track, store, and visualize statistics about data transfers (both paid and unpaid) and earnings from your UrNetwork account. + +The entire application is packaged into a single `main_app.py` file for simplicity, yet it contains robust features including a web-based installer, authentication, public/private views, interactive charts, a provider map, and support for webhook notifications. + +> **A Note from the Author** +> +> I know I might get some hate for using AI to build and refactor this, but since I have access to it for free, I want to make the most of it. Plus, no offense to my friends who can code, but Gemini often explains concepts more clearly! (no hate) +> (this readme is made by ai too.... please just dont hate me, im a stupid bitch-ass idiot that's almost braindead and im not even kidding.) + +----- + +### ✨ Features + + * **🐍 All-in-One Python Script:** The entire application logic, including the frontend, is contained within a single `main_app.py` file. + * **🚀 Web-Based Installer:** A simple setup wizard guides you through configuring your UrNetwork API credentials on the first run. + * **🔐 Dual Views (Public/Private):** + * **Public Dashboard:** Displays summary stats, total data over time, and a world map of provider locations. Perfect for a quick overview. + * **Private Dashboard:** After logging in, you get access to detailed charts, a complete history of data points, webhook management, and other administrative functions. + * **📊 Interactive Charts:** Utilizes `Chart.js` for data visualization, including: + * Total data provided over time. + * Paid vs. Unpaid data comparison. + * A bar chart showing data change between intervals. + * **🗺️ Provider Map:** Displays the number of active providers by country on a world map using `Leaflet.js`. + * **⚙️ Automated Data Collection:** A scheduler (`APScheduler`) automatically fetches and saves new data from the API every 15 minutes. + * **🔔 Webhook Notifications:** Add your own webhook URLs (e.g., for Discord) to receive notifications with each new data sync. + * **🎨 Modern UI:** + * Styled with **Tailwind CSS**. + * **Light/Dark/System theme** support. + * Fully responsive design. + * **💾 Persistent Storage:** Uses `SQLAlchemy` and a `SQLite` database to store historical data. + +----- + +### 🚀 Getting Started + +#### Prerequisites + + * Python 3.x + * Pip (Python package manager) + +#### Installation + +1. **Clone the repository:** + + ```bash + git clone + cd + ``` + +2. **Create and activate a virtual environment (recommended):** + + ```bash + python -m venv venv + # On Windows + .venvScriptsactivate + # On macOS / Linux + source venv/bin/activate + ``` + +3. **Install requirements:** + Create a `requirements.txt` file with the following content: + + ```txt + Flask + Flask-SQLAlchemy + Flask-APScheduler + requests + python-dateutil + gunicorn + ``` + + Then, install them: + + ```bash + pip install -r requirements.txt + ``` + +4. **Run the application:** + + ```bash + python main_app.py + ``` + + *Note: For a production environment, it's better to use a WSGI server like `gunicorn`.* + + ```bash + gunicorn --bind 0.0.0.0:90 main_app:app + ``` + +5. **Web-based Configuration:** + + * Open `http://localhost:90` (or your server's IP address) in your browser. + * You will be redirected to the setup page. Enter your UrNetwork **username** and **password**. + * Upon successful verification, a `.env` file will be created with your credentials and a secret key will be generated for the session. The application is now installed. + +----- + +### 🕹️ Usage + +After installation, the application is ready to use. + + * **Public Dashboard (`/`):** The main page, accessible to anyone. It shows summary stats and the provider map. The data on this page updates automatically every minute without a page refresh. + * **Private Dashboard (`/dashboard`):** + * Click on "Owner Dashboard" to access it. + * Log in using the same credentials you entered during setup. + * Here you will find detailed charts, the full history of all measurements, and you can manage your webhooks. + * **Fetch Now:** Manually triggers a data fetch from the API. + * **Clear All Data:** Deletes all historical data from the database. + * **Webhook Management:** Add or remove URLs for notifications. + +----- + +### 🛠️ Tech Stack + + * **Backend:** [Flask](https://flask.palletsprojects.com/) + * **Database:** [Flask-SQLAlchemy](https://flask-sqlalchemy.palletsprojects.com/) (with SQLite) + * **Job Scheduler:** [Flask-APScheduler](https://github.com/viniciuschiele/flask-apscheduler) + * **Frontend:** [Tailwind CSS](https://tailwindcss.com/), [Chart.js](https://www.chartjs.org/), [Leaflet.js](https://leafletjs.com/) + * **HTTP Requests:** [Requests](https://requests.readthedocs.io/en/latest/) + +----- + +### 🙏 Acknowledgements + + * Original concept and project by **[techroy23](https://github.com/techroy23/UrNetwork-Stats-Dashboard)**. + * This version was completely refactored and extended with the help of AI. + +
+
+
+ +## 🇨🇿 Česky + +### O Projektu + +Tento projekt je výrazně vylepšená a refaktorovaná verze původního [UrNetwork Stats Dashboard](https://github.com/techroy23/UrNetwork-Stats-Dashboard). Aplikace slouží ke sledování, ukládání a vizualizaci statistik o přenesených datech (placených i neplacených) a výdělcích z vašeho účtu v síti UrNetwork. + +Celá aplikace je zabalena do jediného souboru `main_app.py` pro jednoduchost, ale obsahuje robustní funkce, včetně webového instalátoru, autentizace, veřejného a soukromého pohledu, interaktivních grafů, mapy poskytovatelů a podpory pro webhooky. + +> **Poznámka od Autora** +> +> Vím, že asi dostanu hejt za to, že jsem na stavbu a refaktoring použil AI, ale když k tomu mám přístup zadarmo, chci toho co nejvíc využít. Navíc, nic proti mým kamarádům, co umí programovat, ale Gemini mi to často vysvětlí srozumitelněji! (no hate) +> (Tento soubor readme je také vytvořen umělou inteligencí... Prosím, nenávidějte mě, jsem debilní idiot, který je skoro mrtvýmozkově, a to ani nepřeháním.) + +----- + +### ✨ Klíčové Vlastnosti + + * **🐍 All-in-One Python Skript:** Celá logika aplikace, včetně frontendu, je obsažena v jediném souboru `main_app.py`. + * **🚀 Webový Instalátor:** Při prvním spuštění vás provede jednoduchým nastavením přihlašovacích údajů k UrNetwork API. + * **🔐 Dva Pohledy (Public/Private):** + * **Veřejný Dashboard:** Zobrazuje souhrnné statistiky, celkový objem dat v čase a mapu poskytovatelů po celém světě. Ideální pro rychlý přehled. + * **Soukromý Dashboard:** Po přihlášení získáte přístup k detailním grafům, kompletní historii měření, správě webhooků a dalším administrátorským funkcím. + * **📊 Interaktivní Grafy:** Využívá `Chart.js` pro vizualizaci dat, včetně: + * Celkový objem dat v čase. + * Porovnání placených vs. neplacených dat. + * Graf přírůstků dat mezi jednotlivými měřeními. + * **🗺️ Mapa Poskytovatelů:** Zobrazuje na mapě světa (pomocí `Leaflet.js`) počet aktivních poskytovatelů v jednotlivých zemích. + * **⚙️ Automatický Sběr Dat:** Plánovač (`APScheduler`) automaticky stahuje a ukládá data z API každých 15 minut. + * **🔔 Notifikace přes Webhooky:** Možnost přidat si vlastní webhooky (např. pro Discord) a dostávat notifikace při každé nové synchronizaci dat. + * **🎨 Moderní UI:** + * Stylováno pomocí **Tailwind CSS**. + * Podpora **Světlého/Tmavého režimu** s možností synchronizace s nastavením systému. + * Plně responzivní design. + * **💾 Perzistentní Úložiště:** Využívá `SQLAlchemy` a `SQLite` databázi pro ukládání historických dat. + +----- + +### 🚀 Jak začít + +#### Požadavky + + * Python 3.x + * Pip (správce balíčků pro Python) + +#### Instalace + +1. **Klonujte repozitář:** + + ```bash + git clone + cd + ``` + +2. **Vytvořte a aktivujte virtuální prostředí (doporučeno):** + + ```bash + python -m venv venv + # Windows + .venvScriptsactivate + # macOS / Linux + source venv/bin/activate + ``` + +3. **Nainstalujte potřebné balíčky:** + Vytvořte soubor `requirements.txt` s následujícím obsahem: + + ```txt + Flask + Flask-SQLAlchemy + Flask-APScheduler + requests + python-dateutil + gunicorn + ``` + + A poté je nainstalujte: + + ```bash + pip install -r requirements.txt + ``` + +4. **Spusťte aplikaci:** + + ```bash + python main_app.py + ``` + + *Poznámka: Pro produkční nasazení je lepší použít WSGI server jako `gunicorn`.* + + ```bash + gunicorn --bind 0.0.0.0:90 main_app:app + ``` + +5. **Webová konfigurace:** + + * Otevřete v prohlížeči adresu `http://localhost:90` (nebo IP adresu vašeho serveru). + * Budete přesměrováni na instalační stránku. Zde zadejte své **uživatelské jméno** a **heslo** k účtu UrNetwork. + * Po úspěšném ověření se automaticky vytvoří soubor `.env` s vašimi údaji a vygeneruje se tajný klíč pro session. Aplikace se tímto nainstaluje. + +----- + +### 🕹️ Použití + +Po instalaci je aplikace připravena k použití. + + * **Veřejný Dashboard (`/`):** Hlavní stránka dostupná komukoliv. Zobrazuje souhrnné statistiky a mapu. Data na této stránce se automaticky aktualizují každou minutu bez nutnosti obnovení stránky. + * **Soukromý Dashboard (`/dashboard`):** + * Pro přístup klikněte na "Owner Dashboard". + * Přihlaste se pomocí stejných údajů, které jste zadali při instalaci. + * Zde naleznete detailní grafy, historii všech měření a můžete spravovat webhooky. + * **Fetch Now:** Manuálně spustí sběr dat z API. + * **Clear All Data:** Smaže veškerá historická data z databáze. + * **Webhook Management:** Přidávejte nebo odebírejte URL pro notifikace. + +----- + +### 🛠️ Použité Technologie + + * **Backend:** [Flask](https://flask.palletsprojects.com/) + * **Databáze:** [Flask-SQLAlchemy](https://flask-sqlalchemy.palletsprojects.com/) (s SQLite) + * **Plánovač úloh:** [Flask-APScheduler](https://github.com/viniciuschiele/flask-apscheduler) + * **Frontend:** [Tailwind CSS](https://tailwindcss.com/), [Chart.js](https://www.chartjs.org/), [Leaflet.js](https://leafletjs.com/) + * **HTTP Požadavky:** [Requests](https://requests.readthedocs.io/en/latest/) + +----- + +### 🙏 Poděkování + + * Původní koncept a projekt vytvořil **[techroy23](https://github.com/techroy23/UrNetwork-Stats-Dashboard)**. + * Tato verze byla kompletně refaktorována a rozšířena pomocí AI. \ No newline at end of file