NeighborVille

A city-building simulation game with real-time updates and live GitHub-linked versioning. Build a neighborhood, manage resources, and compete on leaderboards.

Features

Core gameplay

• 25+ building types across residential, commercial, utility, and decoration categories
• Coin and resource economy (wood, stone, iron ore) with dynamic pricing and production chains
• Day/night cycle and a weather system that affect building efficiency and resident mood
• 20+ achievements with progress tracking and rewards

Social

• Global leaderboards by level, building count, and city progress
• Public city profiles with privacy controls
• User search to find and follow other players

Infrastructure

• Cloud saves with 30-save history, synced across devices
• Live GitHub integration: the game reads commits from this repo to show real-time version/update info in-app
• Installable as a Progressive Web App, works offline

Moderation

• Username/profile/content filtering with an appeals process
• Admin dashboard for user management and moderation logs
• Two-factor authentication (TOTP + backup codes)

Tech stack

Frontend: React 18, TypeScript, Vite, Tailwind CSS, Framer Motion, Lucide React Backend: Node.js, Express, MongoDB (Mongoose), JWT auth, Nodemailer, express-rate-limit Infra: Docker, Nginx

Quick start

Prerequisites

• Docker & Docker Compose
• Node.js 22+ for local development
• Git

Install

git clone https://github.com/d0mkaaa/neighborville.git
cd neighborville
cp .env.example .env
# edit .env with your configuration

# production
docker-compose up --build

# development, with hot reload
docker-compose -f docker-compose.dev.yml up --build

• Frontend: http://localhost
• API: http://api.localhost

Local development without Docker

# backend
cd server
npm install
npm run dev

# frontend, separate terminal
cd neighborville
npm install
npm run dev

Configuration

Frontend (.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 name

Backend (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 (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.me

Project structure

neighborville/
├── src/                          # Frontend source
│   ├── 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
│   ├── 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

Building system notes

• Buildings can be upgraded for better efficiency and appearance
• Each building requires specific materials to construct
• Grid-based placement with adjacency bonuses
• New players start with 2000 coins; buildings provide daily income based on type and upgrades

Deployment

# set production env vars
NODE_ENV=production
MONGODB_URI=mongodb+srv://your-cluster/neighborville
# ... other production configs

docker-compose -f docker-compose.yml up -d

Health checks:

• Frontend: http://your-domain/
• API: http://your-domain/api/health
• Database: monitor the MongoDB connection

For production, enable gzip in Nginx, consider Redis for session storage, and put static assets behind a CDN.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and test
4. Commit: git commit -m 'Add amazing feature'
5. Push: git push origin feature/amazing-feature
6. Open a pull request

Follow TypeScript conventions, keep test coverage reasonable for new features, and use conventional commit messages.

Support

• Issues: GitHub Issues
• Email: domantas@domkutis.com

License

MIT - see LICENSE.