Shatteredvoid/README.md

# Shattered Void MMO

A post-collapse galaxy MMO strategy game built with Node.js, Express, PostgreSQL, and WebSockets.

## 🎮 Game Overview

Shattered Void is a text-based MMO strategy game set in a post-collapse galaxy where players rebuild civilizations from ruins through colony management, fleet construction, exploration, and participation in dynamic galaxy-wide events.

### Core Features

- **Colony Management**: Build and upgrade colonies across different planet types
- **Fleet Construction**: Design modular ships and manage fleets
- **Research System**: Unlock new technologies and capabilities
- **Dynamic Events**: Participate in admin-driven and player-triggered galaxy events
- **Faction Warfare**: Form alliances and engage in diplomacy
- **Real-time Updates**: WebSocket-powered live game state updates

## 🏗️ Architecture

### Tech Stack

- **Backend**: Node.js with Express framework
- **Database**: PostgreSQL (primary) + Redis (caching/sessions)
- **Real-time**: WebSocket connections for live updates
- **Authentication**: JWT-based with separate admin/player systems
- **Testing**: Jest with comprehensive unit and integration tests

### Project Structure

```
src/
├── config/          # Database, Redis, logging configuration
├── database/        # Migrations, seeds, and query files
├── models/          # Database models organized by domain
├── services/        # Business logic layer
├── controllers/     # HTTP route handlers (API + Admin)
├── middleware/      # Express middleware (auth, validation, etc.)
├── validators/      # Input validation schemas
├── utils/           # Helper functions and utilities
├── plugins/         # Plugin system for extensible game mechanics
├── jobs/            # Background job processing
└── routes/          # Route definitions

tests/
├── unit/            # Unit tests for services, models, utils
├── integration/     # API and database integration tests
├── e2e/             # End-to-end tests
├── fixtures/        # Test data
└── helpers/         # Test utilities
```

## 🚀 Getting Started

### Prerequisites

- Node.js 18+ and npm 9+
- PostgreSQL 14+
- Redis 6+

### Installation

1. Clone the repository
2. Copy environment configuration:
   ```bash
   cp .env.example .env.development
   ```
3. Update `.env.development` with your database credentials
4. Install dependencies:
   ```bash
   npm install
   ```
5. Set up the database:
   ```bash
   npm run db:setup
   ```
6. Start the development server:
   ```bash
   npm run dev
   ```

The server will start on `http://localhost:3000` with WebSocket support.

## 🎯 Game Systems

### Resource Economy
- **Scrap Metal**: Basic building materials
- **Energy Cells**: Power for operations
- **Data Cores**: Advanced technology storage
- **Rare Elements**: Exotic materials for advanced construction

### Colony Management
- Build on 6 different planet types (Terran, Industrial, Research, Mining, Fortress, Derelict)
- Construct 8+ building types with upgrade paths
- Manage population, morale, and defense

### Fleet Operations
- Design custom ships with modular components
- Move fleets across galaxy coordinates (A3-91-X format)
- Engage in instant combat with detailed battle logs

### Research & Technology
- Unlock technologies across 4 categories: Military, Industrial, Social, Exploration
- Build research facilities to accelerate progress
- Prerequisites system for complex tech trees

## 🔧 Development

### Available Scripts

- `npm run dev` - Start development server with hot reload
- `npm run test` - Run test suite with coverage
- `npm run test:watch` - Run tests in watch mode
- `npm run lint` - Run ESLint code quality checks
- `npm run db:migrate` - Run database migrations
- `npm run db:seed` - Populate database with initial data
- `npm run db:reset` - Reset database to clean state

### Code Quality

The project enforces strict code quality standards:
- ESLint configuration with Node.js and Jest rules
- Comprehensive error handling with custom error classes
- Structured logging with Winston and correlation IDs
- Input validation with Joi schemas
- Database transactions for data integrity

### Testing Strategy

- **Unit Tests**: Individual functions and modules
- **Integration Tests**: API endpoints and database operations
- **E2E Tests**: Complete user workflows
- Coverage target: 80%+ for critical game systems

## 🎮 Game Tick System

The game runs on a configurable tick system:
- Default: 60-second intervals
- User groups: Players distributed across 10 processing groups
- Retry logic: 5 attempts with bonus tick compensation
- Real-time monitoring for administrators

## 🔌 Plugin Architecture

Extensible plugin system for game mechanics:
- Combat resolution plugins
- Event system plugins
- Resource calculation plugins
- Custom game rule implementations

## 📊 Admin Features

- Real-time game statistics dashboard
- Event creation and management tools
- Player administration and support
- System configuration with hot-reloading
- Performance monitoring and alerts

## 🔒 Security

- JWT authentication with separate admin/player tokens
- Rate limiting and CORS protection
- Input validation and SQL injection prevention
- Audit logging for all critical operations
- Environment-based configuration management

## 📈 Scalability

Designed to support 100-1000+ concurrent players:
- Connection pooling and query optimization
- Redis caching for frequently accessed data
- User group distribution for tick processing
- Comprehensive indexing strategy
- Performance metrics collection

## 🐳 Deployment

Docker support included:
- Development and production containers
- Docker Compose configurations
- Environment-specific builds
- Automated CI/CD pipeline ready

## 📝 API Documentation

- **Player API**: Authentication, colonies, fleets, research, events
- **Admin API**: System management, player administration, analytics
- **WebSocket Events**: Real-time game state updates
- Full API documentation available in `/docs/api/`

## 🤝 Contributing

1. Follow the existing code style and patterns
2. Write comprehensive tests for new features
3. Update documentation for API changes
4. Use conventional commit messages
5. Run `npm run lint && npm test` before committing

## 📄 License

Private - All rights reserved

---

Built with ❤️ for the post-collapse galaxy simulation community