A modern city-building simulation game with real-time updates, featuring live GitHub integration, comprehensive user management, and family-friendly community features. Build your dream neighborhood, manage resources, compete on leaderboards, and grow your virtual city!
🚀 Live Version: Currently running v1.0.0-live with real-time GitHub integration for instant updates!
- Advanced City Building: Design neighborhoods with 25+ building types including residential, commercial, utilities, and decorations
- Economic Simulation: Manage coins, resources (wood, stone, iron ore), and city budget with dynamic pricing
- Resource Production: Complex production chains with material requirements and building dependencies
- Day/Night Cycle: Dynamic time system affecting gameplay, building efficiency, and visual aesthetics
- Weather System: Dynamic weather patterns impacting city operations and resident mood
- Achievement System: 20+ achievements to unlock with progress tracking and rewards
- Global Leaderboards: Compete with players worldwide by level, building count, and city progress
- User Profiles: Customizable profiles with bio, location, interests, and privacy settings
- Public City Viewing: Showcase your city to other players (with privacy controls)
- User Search: Find and connect with other city builders globally
- Cloud Save System: Automatic cloud saves with 30-save history and cross-device sync
- Live GitHub Integration: Real-time version tracking directly from GitHub repository
- Auto-Updates: Automatic update notifications and version management
- Progressive Web App: Works offline and can be installed on any device
- Family-Safe Environment: Comprehensive content moderation for usernames, profiles, and user content
- Admin Dashboard: Complete user management, moderation logs, and security monitoring
- Suspension System: Unified user and IP suspension with appeal process
- Two-Factor Authentication: TOTP support with backup codes for account security
- Tutorial & Wiki: Comprehensive in-game help system and building encyclopedia
- Settings Management: Granular game settings, audio controls, and accessibility options
- Responsive Design: Fully responsive interface working on desktop, tablet, and mobile
- Animations: Smooth Framer Motion animations throughout the interface
- React 18 - Modern UI framework with concurrent features
- TypeScript - Type-safe development with enhanced IDE support
- Vite - Lightning-fast development and optimized production builds
- Tailwind CSS - Utility-first CSS framework for rapid styling
- Framer Motion - Professional animations and micro-interactions
- Lucide React - Beautiful, consistent iconography
- Node.js + Express - High-performance server architecture
- MongoDB + Mongoose - Flexible NoSQL database with ODM
- JWT Authentication - Secure session management
- Nodemailer - Professional email verification system
- Express Rate Limiting - API protection and abuse prevention
- Docker - Containerized deployment
- Nginx - High-performance web server and reverse proxy
- GitHub Integration - Live version tracking and automated updates
- Environment Management - Secure configuration handling
- Docker & Docker Compose
- Node.js 22+ (for local development)
- Git for repository management
-
Clone the repository:
git clone https://github.com/d0mkaaa/neighborville.git cd neighborville -
Environment setup:
cp .env.example .env # Edit .env with your configuration -
Launch with Docker:
# Production build docker-compose up --build # Development build (with hot reload) docker-compose -f docker-compose.dev.yml up --build
-
Access the application:
- Frontend: http://localhost
- API: http://api.localhost
# Backend server
cd server
npm install
npm run dev
# Frontend development server (new terminal)
cd neighborville
npm install
npm run devFrontend (.env):
VITE_API_URL=http://localhost:3001 # API endpoint
VITE_WS_URL=ws://localhost:3001 # WebSocket endpoint
VITE_EMAIL_FROM=hello@domka.me # Email sender
VITE_EMAIL_FROM_NAME=NeighborVille # Email sender nameBackend (server/.env):
NODE_ENV=development # Environment mode
MONGODB_URI=mongodb://localhost:27017/neighborville
JWT_SECRET=your-super-secure-secret-key
ADMIN_SECRET=neighborville_admin_2024 # Admin promotion key
ADMIN_SETUP_KEY=neighborville-admin-setup-2024
# Email Configuration (Mailtrap for testing)
MAILTRAP_HOST=smtp.mailtrap.io
MAILTRAP_PORT=2525
MAILTRAP_USER=your-mailtrap-user
MAILTRAP_PASS=your-mailtrap-password
EMAIL_FROM=hello@domka.meneighborville/
├── 📁 src/ # Frontend source code
│ ├── 📁 components/ # React components
│ │ ├── 📁 game/ # Game-specific components
│ │ ├── 📁 ui/ # Reusable UI components
│ │ ├── 📁 auth/ # Authentication components
│ │ ├── 📁 admin/ # Admin panel components
│ │ └── 📁 profile/ # User profile components
│ ├── 📁 services/ # API and service layer
│ ├── 📁 data/ # Game data and configurations
│ ├── 📁 types/ # TypeScript type definitions
│ ├── 📁 context/ # React context providers
│ └── 📁 hooks/ # Custom React hooks
├── 📁 server/ # Backend source code
│ ├── 📁 src/
│ │ ├── 📁 controllers/ # Request handlers
│ │ ├── 📁 models/ # Database models
│ │ ├── 📁 routes/ # API route definitions
│ │ ├── 📁 middleware/ # Express middleware
│ │ └── 📁 services/ # Business logic services
│ └── 📁 config/ # Server configuration
├── 📁 public/ # Static assets
├── 📄 docker-compose.yml # Production Docker setup
├── 📄 docker-compose.dev.yml # Development Docker setup
└── 📄 README.md # This file
- 25+ Building Types: Houses, shops, utilities, decorations, and special buildings
- Upgrade Paths: Buildings can be upgraded for better efficiency and appearance
- Resource Requirements: Each building requires specific materials to construct
- Placement Strategy: Grid-based building system with adjacency bonuses
- Starting Capital: New players begin with 2000 coins
- Income Generation: Buildings provide daily income based on type and upgrades
- Resource Trading: Buy and sell materials through the marketplace
- Budget Tracking: Comprehensive financial overview and coin history
- Experience Points: Gain XP through building, upgrading, and daily activities
- Level Unlocks: New buildings and features unlock as you level up
- Achievement Rewards: Bonus coins and XP for completing challenges
- Leaderboard Rankings: Global competition across multiple categories
- Family-Safe Policy: Comprehensive filtering of inappropriate usernames and content
- Real-time Scanning: Automatic detection of prohibited language and patterns
- Appeals Process: Users can appeal moderation decisions through structured system
- Logging: All moderation actions are logged for admin review
- Role-Based Access: User, Moderator, and Admin permission levels
- Account Verification: Email verification required for full account access
- Session Management: Secure session handling with automatic expiration
- Privacy Controls: Users control profile visibility and data sharing
- Real-time version tracking from GitHub repository
- Automatic update notifications when new commits are pushed
- Live commit information displayed in-game
- Seamless update experience without manual version management
- Optimized rendering for large cities (1000+ buildings)
- Improved load times through code splitting and lazy loading
- Memory usage optimization for extended play sessions
- Smooth animations even on lower-end devices
- Modern glassmorphism design language
- Smooth page transitions and micro-interactions
- Improved mobile responsiveness
- Accessibility enhancements for screen readers
- Enhanced content moderation system
- Improved admin tools and security monitoring
- Better rate limiting and abuse prevention
- Secure authentication flow improvements
-
Environment Setup:
# Set production environment variables NODE_ENV=production MONGODB_URI=mongodb+srv://your-cluster/neighborville # ... other production configs
-
Docker Production:
docker-compose -f docker-compose.yml up -d
-
Health Checks:
- Frontend:
http://your-domain/ - API Health:
http://your-domain/api/health - Database: Monitor MongoDB connection
- Frontend:
- Enable gzip compression in Nginx
- Configure Redis for session storage (optional)
- Set up CDN for static assets
- Monitor application metrics and logs
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and test thoroughly
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Follow TypeScript best practices
- Maintain test coverage for new features
- Use conventional commit messages
- Update documentation for new features
- Issues: GitHub Issues
- Email: domantas@domkutis.com
Created by d0mkaaa (Domantas Rutkauskas)
- Passionate full-stack developer from Lithuania 🇱🇹
- Building modern web experiences with love ❤️
- Always open to feedback and collaboration!
This project is licensed under the MIT License - see the LICENSE file for details.
🏙️ NeighborVille v1.0.0-live - Building the future of browser-based city simulation games with cutting-edge web technologies and real-time features.
Made with ❤️ for city builders everywhere | Featuring live GitHub integration and real-time updates! 🚀