2D Metaverse

A full-stack 2D metaverse application built with TypeScript, featuring real-time multiplayer interactions, customizable spaces, and user authentication. Built as a monorepo using Turborepo with Bun as the package manager.

Features

• Real-time Multiplayer: WebSocket-based real-time communication for user interactions
• Space Management: Create and manage custom 2D spaces with dynamic elements
• User Authentication: JWT-based authentication with role-based access control (Admin/User)
• Avatar System: Customizable user avatars
• Map System: Pre-built maps with reusable elements
• Admin Dashboard: Administrative controls for space and element management
• Containerized Deployment: Full Docker support for easy deployment

Architecture

This is a Turborepo monorepo with the following structure:

Applications

• apps/http - REST API server (Express.js)

  • Handles authentication, user management, and space operations
  • Runs on port 3001
  • Built with Express.js and TypeScript

• apps/ws - WebSocket server

  • Real-time communication for multiplayer interactions
  • Runs on port 3003
  • Built with Node.js WebSocket library

• apps/web - Next.js frontend

  • User interface for the metaverse
  • Runs on port 3000
  • Built with Next.js 16 and React 19

Packages

• packages/db - Database layer

  • Prisma ORM with PostgreSQL
  • Shared database client and schema
  • Migrations and database management scripts

• packages/schemas - Validation schemas

  • Zod schemas for request/response validation
  • Shared across HTTP and WS servers

• packages/ui - UI component library

  • Shared React components
  • Used by the web application

• packages/eslint-config - Shared ESLint configurations

• packages/typescript-config - Shared TypeScript configurations

• packages/tests - Test suite

Database Schema

The application uses PostgreSQL with the following main entities:

• User: User accounts with authentication and role-based access
• Space: User-created 2D spaces with dimensions and thumbnails
• Element: Reusable visual elements that can be placed in spaces
• SpaceElements: Junction table linking elements to spaces with coordinates
• Map: Pre-built map templates
• Avatar: User avatar images and metadata

Tech Stack

• Runtime: Bun 1.2.5
• Language: TypeScript 5.9.2
• Monorepo: Turborepo 2.6.3
• Backend: Express.js 5.2.1
• Frontend: Next.js 16.0.10, React 19.2.0
• Database: PostgreSQL 16 with Prisma ORM 7.2.0
• WebSocket: ws 8.19.0
• Authentication: JWT (jsonwebtoken 9.0.3)
• Validation: Zod 4.3.5
• Containerization: Docker & Docker Compose

Prerequisites

• Bun >= 1.2.5
• Docker and Docker Compose (for containerized setup)
• Node.js >= 18 (if not using Docker)
• PostgreSQL 16 (if not using Docker)

🚀 Getting Started

Option 1: Docker Compose (Recommended)

The easiest way to run the entire application:

# Clone the repository
git clone <repository-url>
cd 2d-metaverse

# Create environment file
cp .env.example .env

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

Services will be available at:

• Frontend: http://localhost:3000
• HTTP API: http://localhost:3001
• WebSocket: ws://localhost:3003
• PostgreSQL: localhost:5432

Option 2: Local Development

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your database credentials

# Generate Prisma client
cd packages/db
bunx prisma generate
bunx prisma migrate dev

# Start all services in development mode
cd ../..
bun dev

# Or start individual services
bun dev --filter=@repo/http    # HTTP server only
bun dev --filter=@repo/ws      # WebSocket server only
bun dev --filter=@repo/web     # Frontend only

Available Scripts

Root Level

bun dev              # Start all apps in development mode
bun build            # Build all apps and packages
bun start            # Start all production builds
bun lint             # Lint all packages
bun test             # Run all tests
bun format           # Format code with Prettier
bun check-types      # Type check all packages

Database Commands

cd packages/db

bunx prisma generate    # Generate Prisma client
bunx prisma migrate dev # Create and apply migrations
bunx prisma studio      # Open Prisma Studio GUI

Docker Commands

docker-compose up -d              # Start all services
docker-compose down               # Stop all services
docker-compose logs -f [service]  # View logs
docker-compose restart [service]  # Restart a service
docker-compose ps                 # View running services

API Endpoints

HTTP API (Port 3001)

POST   /api/v1/signup          # User registration
POST   /api/v1/signin          # User login
GET    /api/v1/avatars         # Get all avatars
GET    /api/v1/user/metadata   # Get user metadata

# Space Management
POST   /api/v1/space           # Create a new space
DELETE /api/v1/space/:spaceId  # Delete a space
GET    /api/v1/space/all       # Get all spaces
GET    /api/v1/space/:spaceId  # Get space details
POST   /api/v1/space/element   # Add element to space
DELETE /api/v1/space/element   # Remove element from space

# Admin Routes
POST   /api/v1/admin/element   # Create element (Admin)
PUT    /api/v1/admin/element/:id # Update element (Admin)
POST   /api/v1/admin/avatar    # Create avatar (Admin)
POST   /api/v1/admin/map       # Create map (Admin)

WebSocket (Port 3003)

Real-time events for:

• User movement in spaces
• Space updates
• User interactions

Environment Variables

Required environment variables:

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/metaverse

# Authentication
JWT_SECRET_KEY=your-secret-key-change-in-production

# Server Ports
PORT=3001  # HTTP server port

# Frontend URLs
NEXT_PUBLIC_HTTP_URL=http://localhost:3001
NEXT_PUBLIC_WS_URL=ws://localhost:3003

📁 Project Structure

2d-metaverse/
├── apps/
│   ├── http/          # Express REST API
│   │   ├── src/
│   │   │   ├── index.ts           # Server entry point
│   │   │   ├── middleware/        # Authentication middleware
│   │   │   ├── routes/v1/         # API routes
│   │   │   ├── types/             # TypeScript types
│   │   │   └── utils/             # Helper functions
│   │   ├── Dockerfile
│   │   └── package.json
│   │
│   ├── ws/            # WebSocket server
│   │   ├── src/
│   │   │   ├── index.ts           # WS server entry point
│   │   │   ├── RoomManager.ts     # Room management logic
│   │   │   ├── User.ts            # User connection handling
│   │   │   └── types/
│   │   ├── Dockerfile
│   │   └── package.json
│   │
│   └── web/           # Next.js frontend
│       ├── app/                   # App directory (Next.js 13+)
│       ├── public/
│       ├── Dockerfile
│       └── package.json
│
├── packages/
│   ├── db/            # Prisma database layer
│   │   ├── prisma/
│   │   │   ├── schema.prisma      # Database schema
│   │   │   └── migrations/        # Database migrations
│   │   ├── generated/             # Generated Prisma client
│   │   ├── index.ts
│   │   └── package.json
│   │
│   ├── schemas/       # Zod validation schemas
│   │   ├── index.ts
│   │   └── package.json
│   │
│   ├── ui/            # Shared React components
│   │   ├── src/
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   └── code.tsx
│   │   └── package.json
│   │
│   ├── eslint-config/ # ESLint configurations
│   ├── typescript-config/ # TypeScript configurations
│   └── tests/         # Test suite
│
├── conf/
│   └── nginx.conf     # Nginx reverse proxy configuration
│
├── docker-compose.yml # Docker orchestration
├── turbo.json         # Turborepo configuration
└── package.json       # Root package configuration

Testing

bun test                    # Run all tests
bun test --filter=@repo/tests  # Run specific test package