Initial commit: Shattered Void MMO foundation

- Complete PostgreSQL database schema with 21+ tables - Express.js server with dual authentication (player/admin) - WebSocket support for real-time features - Comprehensive middleware (auth, validation, logging, security) - Game systems: colonies, resources, fleets, research, factions - Plugin-based combat architecture - Admin panel foundation - Production-ready logging and error handling - Docker support and CI/CD ready - Complete project structure following CLAUDE.md patterns 🤖 Generated with Claude Code (https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-02 02:13:05 +00:00 · 2025-08-02 02:13:05 +00:00 · 1a60cf55a3
commit 1a60cf55a3
69 changed files with 24471 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,204 @@
+# 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