🎮 PixelMine - Crypto Mining Game Platform

A comprehensive cryptocurrency mining game platform with room customization, real-time mining, and blockchain integration

Features • Quick Start • Documentation • Architecture

---

📖 За проекта

PixelMine е иновативна криптовалутна игрална платформа, която комбинира елементи от симулационни игри с реална криптовалутна икономика. Играчите могат да създават и управляват виртуални миньорски стаи, да поставят рафтове и майнери, да генерират мощност и да печелят реални криптовалути.

🎯 Основна концепция

Играчите започват с празна стая и постепенно я изграждат като:

• 🏠 Създават стаи - различни типове стаи с различни характеристики
• 📦 Поставят рафтове - рафтовете служат като основа за майнерите
• ⚡ Инсталират майнери - различни типове майнери генерират различна мощност
• 💰 Печелят награди - мощността се преобразува в криптовалути (VRSC, BTC, ETH)
• 🔄 Търгуват - пазар за покупка и продажба на майнери и рафтове
• 🎁 Участват в експедиции - специални събития с уникални награди

---

✨ Features

🎮 Игрални функции

• 🏠 Room System - Създаване и управление на виртуални миньорски стаи
• 📦 Rack System - Поставяне на рафтове в стаите за организиране на майнерите
• ⚡ Miner System - Различни типове майнери с различна мощност и ефективност
• 💎 Power Generation - Реално време изчисляване на мощност от всички майнери
• 📊 Leaderboard - Класация на играчите по мощност и баланс
• 🎯 Tasks & Achievements - Задачи и постижения с награди
• 🗺️ Expeditions - Специални събития и експедиции
• 💬 Live Chat - Реално време чат с Socket.IO

💰 Криптовалутни функции

• 💳 Payment Gateway - Депозити и тегления в BTC, ETH, LTC, DOGE
• 🔐 Wallet Integration - Интеграция с крипто портфейли
• 💵 Balance Management - Управление на баланси в различни криптовалути
• 📈 Exchange Rates - Реално време обменни курсове
• 🔒 Security - KYC/AML проверки и лимити за тегления

👥 Потребителски функции

• 🔐 Authentication - JWT базирана автентификация
• 👤 User Profiles - Профили с статистики и история
• 🎁 Referral System - Реферална система с награди
• 📱 Responsive Design - Работи на всички устройства
• 🌐 Multi-language - Поддръжка на български и английски

🛠️ Админ функции

• 📊 Admin Dashboard - Статистики и мониторинг
• 👥 User Management - Управление на потребители (роли, банове, баланси)
• 💰 Finance Management - Управление на транзакции и плащания
• 🏠 Rooms & Items Management - Управление на стаи, рафтове и майнери
• ⚙️ Settings - Системни настройки и конфигурация
• 📋 Logs & Audit - Логове и аудит на действия
• 🔒 Security - Сигурност и мониторинг
• 📈 Analytics - Аналитика и отчети

---

🏗️ Architecture

Tech Stack

Backend

• Runtime: Node.js 18+
• Framework: Express.js
• Database: MySQL/MariaDB 10.11
• ORM: Prisma 5.7+
• Cache/Queue: Redis 7
• Real-time: Socket.IO 4.7+
• Authentication: JWT (jsonwebtoken)
• Validation: Zod 3.23+
• Security: Helmet, bcryptjs, express-rate-limit

Frontend

• Legacy: Vanilla JavaScript (ES6+)
• Modern: React 18.2+ with Vite
• UI Library: Ant Design 5.12+
• State Management: React Context API
• Routing: React Router 6.21+
• Real-time: Socket.IO Client

Infrastructure

• Containerization: Docker + Docker Compose
• Web Server: Nginx (Alpine)
• Process Manager: Nodemon (development)

Project Structure

faucet/
├── 📁 server/                 # Backend API
│   ├── routes/                # API endpoints (20+ routes)
│   │   ├── admin.js           # Admin routes
│   │   ├── auth.js            # Authentication
│   │   ├── users.js           # User management
│   │   ├── rooms.js           # Room management
│   │   ├── items.js           # Items (racks, miners)
│   │   ├── payments.js        # Payment processing
│   │   └── ...                # More routes
│   ├── services/              # Business logic (12 services)
│   │   ├── userService.js     # User operations
│   │   ├── roomService.js     # Room operations
│   │   ├── paymentsService.js # Payment processing
│   │   ├── miningService.js    # Mining calculations
│   │   └── ...                # More services
│   ├── middleware/            # Express middleware
│   │   ├── auth.js            # JWT authentication
│   │   ├── rbac.js            # Role-based access control
│   │   ├── validation.js      # Request validation
│   │   └── security.js         # Security headers
│   └── handlers/              # Socket.IO handlers
│       ├── chat.js            # Chat events
│       ├── power.js           # Power updates
│       └── rooms.js           # Room events
│
├── 📁 src/                     # Frontend
│   ├── admin/                  # Admin panel (legacy)
│   │   ├── index.html          # Admin dashboard
│   │   └── js/                 # Admin JavaScript
│   ├── legacy/                 # Legacy vanilla JS
│   │   ├── js/                 # Legacy modules
│   │   ├── css/                # Legacy styles
│   │   └── *.html              # Legacy pages
│   ├── react/                  # Modern React app
│   │   ├── components/         # React components
│   │   ├── pages/              # Page components
│   │   ├── layouts/            # Layout components
│   │   ├── hooks/              # Custom hooks
│   │   └── utils/              # Utilities
│   └── shared/                 # Shared code
│       ├── api/                # API client
│       └── socket/             # Socket client
│
├── 📁 prisma/                  # Database schema
│   └── schema.prisma           # Prisma schema (42 tables)
│
├── 📁 database/                # SQL files
│   ├── schema.sql              # Initial schema
│   ├── seed.sql                # Seed data
│   └── migrations/             # SQL migrations
│
├── 📁 docs/                     # Documentation
│   ├── ADMIN_API.md            # Admin API docs
│   ├── DATABASE.md              # Database docs
│   ├── DEVELOPMENT.md           # Development guide
│   └── ...                      # More docs
│
├── 📁 scripts/                  # Utility scripts
│   ├── backup-database.sh       # Database backup
│   ├── setup-docker.sh          # Docker setup
│   └── ...                      # More scripts
│
├── 📁 assets/                   # Static assets
│   ├── images/                  # Images
│   └── icons/                   # Icons
│
├── docker-compose.yml           # Docker Compose config
├── Dockerfile                   # Docker image
├── nginx.conf                   # Nginx config
├── package.json                 # Dependencies
└── README.md                    # This file

Database Schema

Платформата използва 42 таблици в MySQL/MariaDB база данни:

Core Tables

• users - Потребители (id, email, username, balance, power, role, etc.)
• user_rooms - Стаи на потребители
• user_racks - Рафтове в стаи
• user_miners - Майнери на рафтове
• items - Предмети (рафтове, майнери, декорации)
• item_templates - Шаблони за предмети

Financial Tables

• payment_transactions - Транзакции за плащане
• payment_addresses - Крипто адреси
• transactions - Вътрешни транзакции
• withdrawals - Тегления

Game Tables

• expeditions - Експедиции
• tasks - Задачи
• leaderboard - Класация
• referrals - Реферали

Admin Tables

• audit_logs - Аудит логове
• admin_logs - Админ логове
• system_settings - Системни настройки
• menu_sets - Меню конфигурации
• menu_items - Меню елементи

Social Tables

• chat_messages - Чат съобщения
• user_friends - Приятели
• notifications - Известия

API Structure

Public Endpoints

• POST /api/auth/register - Регистрация
• POST /api/auth/login - Вход
• GET /api/health - Health check
• GET /api/settings - Публични настройки

Protected Endpoints (User)

• GET /api/users/me - Текущ потребител
• GET /api/rooms - Стаи на потребителя
• POST /api/rooms - Създаване на стая
• GET /api/items - Предмети
• GET /api/transactions - Транзакции
• GET /api/leaderboard - Класация

Admin Endpoints

• GET /api/admin/stats - Статистики
• GET /api/admin/users - Списък потребители
• PUT /api/admin/users/:id - Редактиране потребител
• GET /api/admin/transactions - Всички транзакции
• GET /api/admin/logs - Логове

---

🚀 Quick Start

Prerequisites

• Docker 20.10+ и Docker Compose 2.0+
• Git за клониране на репозитория
• Node.js 18+ (за локална разработка)

Installation

1. Клонирай репозитория:

git clone https://git.vi-lab.eu/orion/faucet.git
cd faucet

2. Копирай environment файл (опционално):

cp .env.example .env

3. Стартирай Docker stack:

docker-compose up -d

4. Провери статуса:

docker-compose ps

5. Достъп до приложението:

• 🌐 Main site: http://localhost:7007
• 🛠️ Admin panel: http://localhost:7007/admin/index.html
• 🔌 API: http://localhost:7007/api
• 📊 API Health: http://localhost:7007/api/health

Default Admin Credentials

• Email: rott@mail.bg
• Username: ghost
• Password: nokia1

⚠️ Важно: Смени паролата след първо влизане!

---

📚 Documentation

Основна документация

• 📖 QUICK_START.md - Бързо стартиране
• 📖 INSTALLATION.md - Подробна инсталация
• 📖 PROJECT_STRUCTURE.md - Структура на проекта
• 📖 DATABASE_ANALYSIS.md - Анализ на базата данни

Техническа документация

• 🔧 docs/DEVELOPMENT.md - Разработка
• 🔧 docs/DOCKER.md - Docker setup
• 🔧 docs/DATABASE_SETUP.md - Database setup
• 🔧 docs/ADMIN_API.md - Admin API

Планове за развитие

• 🚀 INNOVATION_PLAN.md - План за иновации
• 📋 PHASE1_COMPLETE.md - Фаза 1 завършена
• 📋 PHASE2_HEALTH_CHECK.md - Фаза 2 проверка

---

🛠️ Development

Development Mode

Проектът използва Nodemon за автоматично рестартиране на API сървъра при промени:

# API автоматично рестартира при промени в server/
docker-compose logs -f api

Available Scripts

# Development
npm run dev              # Стартира API с nodemon
npm run frontend         # Стартира frontend dev server

# Docker
npm run docker:up        # Стартира Docker stack
npm run docker:down      # Спира Docker stack
npm run docker:logs      # Показва логове

# Database
npm run backup:db        # Backup на базата данни
npm run migrate:dev      # Prisma migrations (dev)
npm run migrate:deploy   # Prisma migrations (production)

# Production
npm run prod:up          # Стартира production stack
npm run ssl:setup        # SSL setup с Let's Encrypt

Environment Variables

Основните environment променливи (с default стойности):

# Database
DB_HOST=mysql
DB_PORT=3306
DB_USER=project_user
DB_PASS=strong_password
DB_NAME=pixelmine_db

# Server
PORT=3000
NODE_ENV=development
CORS_ORIGIN=http://localhost:7007

# Admin
ADMIN_EMAIL=rott@mail.bg
ADMIN_USERNAME=ghost
ADMIN_PASSWORD=nokia1

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=redis_password

# JWT
JWT_SECRET=your-secret-key-here

---

🔒 Security

Implemented Security Features

• ✅ JWT Authentication - Secure token-based auth
• ✅ RBAC (Role-Based Access Control) - Гранулирани права
• ✅ Password Hashing - bcryptjs с salt
• ✅ Rate Limiting - Защита срещу brute force
• ✅ Helmet.js - Security headers
• ✅ Input Validation - Zod schema validation
• ✅ SQL Injection Protection - Prisma ORM
• ✅ XSS Protection - Input sanitization
• ✅ CORS Configuration - Контролиран достъп
• ✅ Audit Logging - Логване на всички действия

Security Best Practices

• 🔐 Винаги използвай силни пароли
• 🔐 Не споделяй JWT tokens
• 🔐 Регулярно backup на базата данни
• 🔐 Мониторинг на логовете за подозрителна активност
• 🔐 Регулярни обновления на зависимостите

---

📊 Current Status

✅ Completed (v0.1)

• ✅ Базова структура на базата данни (42 таблици)
• ✅ User management система
• ✅ Admin panel с основни функции
• ✅ Room/Rack/Miner система (структура)
• ✅ Payment transactions таблица
• ✅ Online/Offline статус за потребители
• ✅ API endpoints за основните операции
• ✅ Authentication и authorization система
• ✅ Real-time updates с Socket.IO
• ✅ Redis caching и queues

⚠️ In Progress

• ⚠️ Room/Rack/Miner UI (структурата е готова, но UI трябва да се подобри)
• ⚠️ Payment система (таблицата съществува, но логиката трябва да се допълни)
• ⚠️ Admin menu система (базовата структура е готова)

🚀 Planned Features

• 🚀 Гъвкаво админ меню (Menu Builder)
• 🚀 Подобрена Room → Racks → Miners система
• 🚀 Икономика (награди, difficulty, ROI)
• 🚀 Пълна Payment система (crypto integration)
• 🚀 React migration (от legacy JS)

---

🤝 Contributing

Виж CONTRIBUTING.md за подробности как да допринесеш.

Development Workflow

1. Fork репозитория
2. Създай feature branch (git checkout -b feature/amazing-feature)
3. Commit промените (git commit -m 'Add amazing feature')
4. Push към branch (git push origin feature/amazing-feature)
5. Отвори Pull Request

---

📝 License

Този проект е лицензиран под MIT License - виж LICENSE файла за подробности.

---

👥 Team

Разработено от: Vi Team Security Group

• 📧 Email: rott@mail.bg
• 🌐 Website: https://git.vi-lab.eu/orion/faucet
• 📝 Copyright © 2024 Vi Team Security Group. All rights reserved.

---

🙏 Acknowledgments

• Prisma - Отличен ORM за TypeScript/Node.js
• Express.js - Минималистичен web framework
• React - UI библиотека
• Socket.IO - Real-time комуникация
• Docker - Containerization платформа

---

📞 Support

За въпроси и поддръжка:

• 📧 Email: rott@mail.bg
• 🐛 Issues: https://git.vi-lab.eu/orion/faucet/issues
• 📖 Documentation: docs/

---

Made with ❤️ by Vi Team Security Group

⭐ Star this repo if you find it useful!