Universal Sats

A production-grade, full-stack Bitcoin mining clicker game inspired by Universal Paperclips, built with modern web technologies.

Tech Stack

Frontend

• Next.js 15 (App Router) with TypeScript
• React 19
• TailwindCSS
• shadcn/ui components
• Framer Motion for animations
• Zustand for state management
• Recharts for data visualization

Backend

• NestJS with TypeScript
• PostgreSQL with Prisma ORM
• Redis + BullMQ for background jobs
• Socket.io for real-time updates
• NextAuth v5 for authentication

Project Structure

├── backend/          # NestJS backend application
├── frontend/         # Next.js frontend application
├── docker-compose.yml
└── README.md

Getting Started

Prerequisites

• Node.js 20+
• PostgreSQL 14+
• Redis 7+
• Docker (optional, for containerized setup)

Local Development

1. Install dependencies:

   npm install

2. Set up environment variables:

   Create .env files in both backend/ and frontend/ directories. See .env.example files for required variables.

3. Set up the database:

   cd backend
   npx prisma migrate dev
   npx prisma generate
   npm run seed

4. Start Redis:

   redis-server

   Or use Docker:

   docker run -d -p 6379:6379 redis:7-alpine

5. Start the development servers:

   npm run dev

   This will start:

   • Backend on http://localhost:3001
   • Frontend on http://localhost:3000

Database Migrations

Run migrations:

cd backend
npx prisma migrate dev

Generate Prisma client:

npx prisma generate

Seeding Data

Seed the database with initial game data:

cd backend
npm run seed

Game Engine Architecture

The game engine runs server-side using BullMQ background jobs:

• Tick System: Runs every second, updating player resources (satoshis from hashrate)
• Market Simulation: Updates BTC price and network difficulty periodically
• World Events: Generates random market events that affect gameplay
• Difficulty Recalculation: Adjusts mining difficulty based on network hashrate

Tick System

The tick system is the core of the game engine. It:

1. Processes all active players
2. Calculates satoshi generation based on hashrate
3. Updates energy costs
4. Persists state changes
5. Emits real-time updates via WebSocket

Ticks run every second via BullMQ scheduled jobs. The system is designed to handle thousands of concurrent players efficiently.

AI Integration Points

The game includes several AI modules that can be enhanced with GPT-style AI:

1. Miner Manager AI (backend/src/game/ai/miner-manager.ai.ts)

   • Currently uses greedy ROI optimization
   • Replace decideHardwarePurchase() with GPT calls

2. Energy Optimizer AI (backend/src/game/ai/energy-optimizer.ai.ts)

   • Currently uses cost-benefit analysis
   • Replace optimizeEnergyUsage() with GPT calls

3. Market Trader AI (backend/src/game/ai/market-trader.ai.ts)

   • Currently uses simple trend following
   • Replace decideTrade() with GPT calls

4. Empire AI (backend/src/game/ai/empire.ai.ts)

   • Coordinates all AI modules
   • Replace makeStrategicDecision() with GPT calls

All AI modules are marked with // AI_INTEGRATION_POINT comments where GPT API calls should be added.

Testing

Run tests:

npm run test

Run backend tests:

cd backend
npm run test

Run frontend tests:

cd frontend
npm run test

Deployment

Backend (Fly.io or AWS ECS)

1. Build Docker image:

   cd backend
   docker build -t bitcoin-mining-backend .

2. Deploy using Fly.io:

   flyctl deploy

Frontend (Vercel)

1. Connect your repository to Vercel
2. Configure environment variables
3. Deploy automatically on push

Environment Variables

Backend

• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection string
• JWT_SECRET - JWT signing secret
• NEXT_AUTH_SECRET - NextAuth secret
• NEXT_AUTH_URL - Frontend URL for NextAuth

Frontend

• NEXT_PUBLIC_API_URL - Backend API URL
• NEXT_PUBLIC_WS_URL - WebSocket URL
• NEXTAUTH_SECRET - NextAuth secret
• NEXTAUTH_URL - Frontend URL

Contributing

1. Create a feature branch
2. Make your changes
3. Run tests and linting
4. Submit a pull request

License

MIT