---

name: hytaleservers-workflow description: "Standard workflow for HyTaleServers.tech development"

HyTaleServers Workflow

Project Overview

Name: Hytaleservers.tech
Description: Мониторинг и топ-лист серверов Hytale
Stack: Next.js 16 + Supabase + Tailwind CSS + shadcn/ui
Status: Production ready
Version: 0.1.0

Development Flow

1. Create feature branch: git checkout -b feature/xxx
2. Make changes
3. Test locally: npm run dev (port 3000)
4. Commit: git commit -m "feat: xxx"
5. Push: git push origin feature/xxx
6. Create PR on GitHub
7. After merge → auto-deploy to VPS (port 3003)

Available Commands

Development

• npm run dev - dev server (port 3000)
• npm run build - production build
• npm start - production server
• npm run lint - linting

Setup

• npm run create-admin - create admin user
• npm run deploy - deploy to VPS

Project Structure

Copyhytaleservers-tech/
├── app/                    # Next.js App Router
│   ├── api/                # API routes (11 endpoints)
│   │   ├── servers/        # Servers API
│   │   ├── categories/     # Categories API
│   │   ├── admin/          # Admin API
│   │   └── ...             # Other endpoints
│   ├── page.tsx            # Main page
│   ├── layout.tsx          # Root layout
│   └── globals.css         # Global styles
├── components/             # React components
│   ├── server/             # Server components
│   ├── shared/             # Shared components
│   └── ui/                 # shadcn/ui components
├── lib/                    # Utilities
│   ├── supabase/           # Supabase clients
│   │   ├── client.ts       # Browser client
│   │   └── server.ts       # Server client
│   └── utils/              # Helper functions
├── supabase/               # Database
│   ├── migrations/         # SQL migrations (001-003)
│   └── seed.sql            # Test data
├── scripts/                # Utility scripts
│   ├── create-admin.ts     # Create admin
│   ├── setup-storage.ts    # Setup storage
│   └── deploy-vps.sh       # Deploy script
└── .env                    # Environment variables (VPS)

Database

Supabase Configuration

• URL: https://ncxelqwplkhlhvbmdatf.supabase.co
• Storage buckets: server-logos, server-banners
• Current setup: Single Supabase project for both local and production

Tables

• servers - Hytale servers

  • id (UUID, PK)
  • name, slug, ip, port
  • descriptions, logo_url, banner_url
  • owner_email, secret_key
  • status, current_players, max_players
  • rating, uptime_percentage, total_votes

• categories - Server categories

  • id (UUID, PK)
  • name, slug, icon, description

• server_categories - Junction table

  • server_id (FK servers.id)
  • category_id (FK categories.id)

• votes - Votes for servers

  • id (UUID, PK)
  • server_id (FK servers.id)
  • user_id (FK auth.users.id)
  • ip_address, user_agent, voted_at

• admin_users - Admin users

  • email (PK)
  • password_hash

Migrations

1. 001_initial_schema.sql - Main schema (servers, categories, votes)
2. 002_profiles.sql - User profiles
3. 003_storage.sql - Storage buckets (logos, banners)

Seed Data

• 14 categories (survival, pvp, pve, rpg, creative, minigames, etc.)
• 3 test servers (HyWorld Survival, PvP Arena, Creative Build)

Environment Variables

Local Development (.env.local)

Copy# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://ncxelqwplkhlhvbmdatf.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=sb_publishable_h4MJcTegWY2W93zWfGmkVQ_E2QSDnRH
SUPABASE_SERVICE_ROLE_KEY=...

# Site Configuration
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Analytics (empty for local)
NEXT_PUBLIC_GA_ID=
NEXT_PUBLIC_YANDEX_METRIKA_ID=

# Optional: Telegram Bot (empty for local)
TELEGRAM_BOT_TOKEN=
TELEGRAM_WEBHOOK_SECRET=

# Optional: Stripe (empty for local)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

Production (.env on VPS)

Copy# Same as local except:
NEXT_PUBLIC_SITE_URL=http://localhost:3003
# (or https://hytaleservers.tech in future)

Port Configuration

• Local (dev): 3000 (Next.js default)
• VPS (production): 3003 (PM2 config)

Deployment

Automatic (GitHub Actions)

Push to main branch → auto-deploy to VPS

Required GitHub Secrets:

• GH_SSH_PRIVATE_KEY - Private SSH key
• VPS_HOST - VPS IP or domain
• VPS_USER - User (usually root)
• VPS_PATH - Project path (/root/hytaleservers-tech)

Manual

Copy./scripts/deploy-vps.sh

# Or manually
git pull origin main
npm install --production
npm run build
pm2 restart hytaleservers

API Routes

Public

• GET /api/servers - List servers (with pagination, filters, sorting)
  • Query params: page, limit, sort, category, search, status
• GET /api/servers/[id] - Server details
• GET /api/categories - List categories
• GET /api/servers/test - Test endpoint

Auth Required

• GET /api/my-servers - User's servers
• POST /api/upload - Upload images (logo/banner)
• GET /api/admin-moderation/[id] - Moderation queue

Admin

• POST /api/admin/login - Admin login (sets cookie)
• POST /api/admin/logout - Admin logout (clears cookie)

Debug

• GET /api/test - API test
• GET /api/debug - Debug info
• GET /api/supabase-test - Supabase connection test

Important Files

Documentation

• HISTORY.md - MANDATORY - Project change history (iterations, decisions, problems) - UPDATE AFTER EVERY ITERATION
• LOCAL_SETUP.md - Local setup instructions for AI assistant
• PROJECT_MAP.md - Detailed project documentation (553 lines)
• README.md - Main README with setup instructions

Configuration

• package.json - Dependencies and scripts
• tsconfig.json - TypeScript configuration
• tailwind.config.ts - Tailwind CSS configuration
• next.config.ts - Next.js configuration
• ecosystem.config.js - PM2 configuration
• .gitignore - Git ignore rules

Scripts

• scripts/create-admin.ts - Create admin user (hardcoded password)
• scripts/setup-storage.ts - Storage setup instructions
• scripts/fix-storage.ts - Storage fixes
• scripts/deploy-vps.sh - Deploy script (bash)

Tech Stack Details

Frontend

• Framework: Next.js 16.1.1 (App Router)
• UI Library: React 19.2.3
• Language: TypeScript 5
• Styling:
  • Tailwind CSS 4
  • shadcn/ui (New York style)
  • Radix UI (Select, Slot)
  • Framer Motion 12.26.2 (animations)
  • class-variance-authority, clsx, tailwind-merge

State & Data

• State Management: Zustand 5.0.10
• Data Fetching: TanStack Query 5.90.17
• Validation: Zod 4.3.5

Backend & API

• API Framework: Next.js API Routes
• Server-Side Rendering: Next.js SSR with @supabase/ssr

Database

• Provider: Supabase (PostgreSQL)
• Client: @supabase/supabase-js 2.90.1
• SSR Client: @supabase/ssr 0.8.0

Deployment

• Process Manager: PM2 (production)
• Port: 3003 (VPS), 3000 (local)
• Environment: Linux (Ubuntu on VPS), Windows (local)

Development

• Package Manager: npm
• Build Tool: Turbopack (Next.js 16)
• Linting: ESLint 9 + eslint-config-next

Current Status

✅ Working

• Next.js 16 with App Router
• Supabase connection (ANON KEY)
• API endpoints (servers, categories, admin, etc.)
• PM2 production server (port 3003)
• Supabase Skills for OpenCode (5 skills)
• shadcn/ui components
• Tailwind CSS 4
• Middleware for admin routes
• Image upload to Supabase Storage
• Server moderation system

⚠️ Issues

• Service Role KEY needs update (currently using ANON KEY in ecosystem.config.js)
• No tests implemented
• Analytics not configured (GA, Yandex Metrika)
• Telegram Bot not configured
• Stripe not configured

❌ Not Implemented

• Vote system
• Server monitoring (ping)
• Admin panel UI
• Server registration form (public)
• Filters and search on main page
• Pagination
• SEO optimization (sitemap, robots.txt)

Development Guidelines

Code Style

• Follow existing patterns in components
• Use TypeScript for all new files
• Use shadcn/ui components for UI
• Follow Supabase SSR patterns for server components

Database Changes

1. Create migration in supabase/migrations/XXX_description.sql
2. Apply migration via Supabase CLI or Dashboard
3. Update TypeScript types if needed
4. Test locally and on production

Adding New Features

1. Create feature branch
2. Implement feature
3. Test locally
4. Commit with conventional commits (feat:, fix:, etc.)
5. Push and create PR
6. After merge → auto-deploy

Adding New API Routes

• Place in app/api/[resource]/route.ts
• Use lib/supabase/server.ts for server client
• Return JSON responses
• Add error handling

Documentation Management

MANDATORY: Update HISTORY.md after every iteration

After completing development work (feature, bug fix, refactoring, etc.), you MUST update HISTORY.md:

When to update:

• After any iteration of development (not just git commits)
• After debugging sessions
• After architectural decisions
• After testing and fixes

How to update:

1. Add new entry at the top of HISTORY.md with current date
2. Include ALL relevant sections:
   • 📝 Изменения кода - what was changed
   • 💡 Принятые решения - why decisions were made
   • 🐛 Проблемы и решения - issues encountered and fixed
   • ✅ Задачи (TODO) - completed and pending tasks with tags [bug]/[feature]/[refactor] and priority high/medium/low
   • 🔧 Технические заметки - important technical details
   • 🎯 Результат - outcome of the iteration

Format:

Copy## [ГГГГ-ММ-ДД] - Итерация N

### 📝 Изменения кода
- [Description]

### 💡 Принятые решения
- **[Decision]**: [Description]
  - Почему: [Reason]
  - Альтернативы: [Alternatives]

### 🐛 Проблемы и решения
- **[Problem]**: [Description]
  - Решение: [How fixed]
  - Время: [Time spent]

### ✅ Задачи (TODO)
- [x] [Task] - [tag] [priority]
- [ ] [Task] - [tag] [priority]

### 🔧 Технические заметки
- [Technical details]

### 🎯 Результат
[Outcome summary]

CRITICAL RULES:

• ALWAYS update HISTORY.md before moving to next task
• Include ALL changes, even minor ones
• Tag tasks with [bug]/[feature]/[refactor]
• Mark task priority as high/medium/low
• Document both successes and failures
• Keep entries machine-readable (AI needs to parse them)

Testing Checklist

Before Pushing

• Run npm run lint - check for linting errors
• Test locally with npm run dev
• Test API endpoints
• Check console for errors
• Verify Supabase connection
• CRITICAL: Update HISTORY.md with all changes, decisions, and problems

After Deployment

• Check PM2 status: pm2 status
• Check PM2 logs: pm2 logs hytaleservers
• Test API endpoints on production
• Check UI in browser
• Verify Supabase connection

Future Features

Priority 1 - Critical

1. Update Service Role KEY
2. Implement vote system
3. Implement server monitoring (ping)
4. Add pagination to servers list
5. Add filters and search to main page

Priority 2 - Important

1. Implement admin panel UI
2. Implement server registration form (public)
3. Setup analytics (GA, Yandex Metrika)
4. Add tests (Jest/Vitest)
5. Setup CI/CD for staging

Priority 3 - Nice to Have

1. Implement Telegram Bot for notifications
2. Implement Stripe for premium features
3. SEO optimization (sitemap, robots.txt)
4. Performance monitoring
5. Error tracking (Sentry, etc.)

Useful Commands

Development

Copynpm run dev              # Start dev server
npm run build            # Build for production
npm start                # Start production server
npm run lint             # Check linting

Database

Copynpm run create-admin     # Create admin user
# (Currently hardcoded password in script)

Deployment

Copynpm run deploy          # Deploy to VPS
# or
./scripts/deploy-vps.sh

PM2 (on VPS)

Copypm2 status              # Check status
pm2 logs hytaleservers # View logs
pm2 restart hytaleservers
pm2 stop hytaleservers
pm2 start hytaleservers

Git

Copygit checkout -b feature/xxx
git add .
git commit -m "feat: xxx"
git push origin feature/xxx

Troubleshooting

Issue: Dev server not starting

• Check port 3000 is free: lsof -i :3000 (Mac/Linux) or netstat -ano | findstr :3000 (Windows)
• Check .env.local exists and is valid
• Check node_modules are installed

Issue: Supabase connection error

• Check .env.local has correct Supabase URL and keys
• Check Supabase project is accessible
• Check console for error details

Issue: Build fails

• Check for TypeScript errors
• Check for missing dependencies
• Check linting errors

Issue: Deploy fails

• Check SSH connection to VPS
• Check PM2 is running on VPS
• Check deploy script permissions

Resources

Documentation

• Next.js Docs
• Supabase Docs
• shadcn/ui Docs
• Tailwind CSS Docs

Project

• Supabase Dashboard: https://supabase.com/dashboard/project/ncxelqwplkhlhvbmdatf
• Local URL: http://localhost:3000
• Production URL: http://localhost:3003 (or https://hytaleservers.tech)

External

• GitHub Repository: (to be created)
• Issue Tracker: (GitHub Issues)
• Documentation: (PROJECT_MAP.md, README.md, LOCAL_SETUP.md)

---

Last Updated: January 17, 2026
Maintainer: AI Assistant (OpenCode)
Status: Active Development