PØSSESSƏD - Location-Based AR Game

A full-stack location-based augmented reality mobile game featuring real-time multiplayer interactions, geospatial gameplay, and push notifications. Players place "curses" (virtual entities) at real-world locations or on other users, competing to level up through strategic placement and destruction of these AR/GIS entities.

🎯 What is PØSSESSƏD?

PØSSESSƏD is an innovative location-based AR game where players "possess the world" by placing curses at real-world GPS coordinates or directly on other players. The game combines real-world exploration with strategic gameplay, encouraging players to explore their surroundings while competing against others in a persistent multiplayer world.

Core Gameplay:

• Place curses at physical locations or on other users
• Destroy curses placed by others to gain experience
• Level up your character through conquest
• Earn and spend "curse credits" (in-app currency)
• Compete on leaderboards
• Real-time notifications when your curses are destroyed
• Strategic resource management (energy, weapons, credits)

📱 Tech Stack

Mobile App (packages/mobile-app)

• Framework: React Native 0.66.3
• State Management: Redux Toolkit with Redux Persist
• Navigation: React Navigation 4.x (Stack, Drawer, Tabs)
• Maps: React Native Maps with Geolocation tracking
• Real-time: Socket.IO Client for live multiplayer events
• UI Components: React Native Elements
• Animations: React Native Animatable & Reanimated
• Storage: AsyncStorage with Redux Persist
• Language: TypeScript
• HTTP Client: Axios

Backend (packages/backend)

• Runtime: Node.js 14.x
• Framework: Express.js
• Database: MongoDB with Mongoose ODM
• Caching: Redis with Redis Adapter for Socket.IO
• Real-time: Socket.IO Server (with Redis pub/sub for scaling)
• Authentication: JWT (JSON Web Tokens) with BCrypt password hashing
• Push Notifications: Apple Push Notification Service (APN)
• Email: Gmail integration via gmail-send
• Cloud Services: AWS Lambda client integration
• Rate Limiting: redis-rate-limiter for API protection
• Testing: Jest with MongoDB Memory Server
• ID Generation: shortid for unique entity IDs

🏗️ Architecture

System Components

┌─────────────────┐
│  Mobile App     │ (React Native)
│  (iOS/Android)  │
└────────┬────────┘
         │
         │ REST API (HTTP)
         │ WebSocket (Socket.IO)
         │
┌────────▼────────┐
│ Express Server  │
│ + Socket.IO     │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
┌───▼──┐  ┌──▼───┐
│MongoDB│  │ Redis│
│ (Data)│  │(Cache│
└───────┘  │& Pub/│
           │ Sub) │
           └──────┘

Key Components

1. Express REST API (packages/backend)

   • User authentication and management
   • AR/GIS entity CRUD operations (curses)
   • Activity feed tracking
   • Leaderboard queries
   • Admin utilities (push notifications, contact forms)
   • Static landing page serving

2. Socket.IO Real-time Server (packages/backend/api/library/socket.js)

   • Real-time event broadcasting
   • User room subscriptions
   • Redis adapter for horizontal scaling
   • Events: userCursed, creditRateChanged

3. MongoDB Database (Mongoose models)

   • Users: Player profiles, stats, credentials, device tokens
   • ArGis: Curse entities with geospatial data (location or user-targeted)
   • Activity: Player actions (attach location/user, destroy, friend)

4. React Native Mobile App (packages/mobile-app)

   • Redux Toolkit for state management
   • React Native Maps for geolocation visualization
   • Socket.IO client for real-time updates
   • Persistent storage with Redux Persist

🔑 Core Features

Gameplay Mechanics

Curse System:

• Location-Based Curses: Place curses at real-world GPS coordinates tied to named locations
• User-Targeted Curses: Attack other players directly by placing curses on them
• Curse Credits: In-app currency used to place curses (costs vary)
• Destruction: Destroy enemy curses to gain experience and reduce their credit earnings
• Anonymous Placement: Option to place curses anonymously

Character Progression:

• Experience & Leveling: Gain XP by destroying curses; level up at (level^1.2) * 30 XP
• Level-Up Points: Spend on permanent upgrades (energy, weapons, regeneration)
• Stats:
  • experience: Current XP towards next level
  • level: Current character level
  • levelUps: Available upgrade points
  • curseCredits: Currency for placing curses
  • totalEnergyFactor: Max energy capacity multiplier
  • energyRegenerationFactor: Energy recovery speed multiplier
  • weaponRegenerationFactor: Weapon recharge speed multiplier

Resource Management:

• Energy System: Time-based regeneration for actions
• Credit Refresh: Periodic credit regeneration mechanism
• Session Tracking: creditsEarnedSession tracks earnings per session

Social Features

• ✅ Activity feed (friend actions, attachments, destroys)
• ✅ Leaderboard system (by experience/level)
• ✅ User search functionality
• ✅ Real-time notifications when cursed or destroyed
• ✅ Tutorial system for new players

Technical Features

• ✅ JWT-based authentication with bcrypt password hashing
• ✅ Redis-based rate limiting (IP and token-based)
• ✅ Geospatial queries with MongoDB Point schema
• ✅ Real-time multiplayer via Socket.IO with Redis adapter
• ✅ iOS push notifications via APN
• ✅ Email notifications (Gmail SMTP)
• ✅ Password reset functionality
• ✅ CORS-enabled admin endpoints
• ✅ Static landing page with game info
• ✅ Privacy policy & terms of service pages

🚀 Getting Started

Prerequisites

• Node.js 14.x or later
• MongoDB (local or hosted)
• Redis (local or hosted)
• React Native development environment
  • iOS: Xcode with CocoaPods
  • Android: Android Studio with SDK
• (Optional) Apple Developer account for push notifications

Backend Setup

cd packages/backend

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env
# Edit .env with your configuration:
# - MONGODB_URI: MongoDB connection string
# - REDIS_HOST, REDIS_PORT, REDIS_KEY: Redis connection details
# - JWT_SECRET: Secret for JWT token signing
# - GMAIL_USER, GMAIL_PASS: Gmail SMTP credentials
# - APN_KEY_ID, APN_TEAM_ID, APN_KEY: Apple Push Notification credentials

# Start MongoDB (if running locally)
mongod

# Start Redis (if running locally)
redis-server

# Run development server (defaults to port 2012)
npm run start-dev

# Run production server (uses PORT env variable)
npm start

# Run tests
npm test

Mobile App Setup

cd packages/mobile-app

# Install dependencies
npm install

# iOS: Install CocoaPods dependencies
cd ios && pod install && cd ..

# Configure environment
cp .env.example .env
# Edit .env with your backend API URL

# Run on iOS
npm run ios

# Run on Android
npm run android

# Run tests
npm test

# Run linter
npm run lint

# Format code
npm run pretty

📂 Project Structure

possessed-monorepo/
├── packages/
│   ├── mobile-app/              # React Native mobile application
│   │   ├── __tests__/           # Jest test files
│   │   ├── android/             # Android native code
│   │   ├── ios/                 # iOS native code
│   │   └── app/                 # Application source code
│   │       ├── actions/         # Redux action creators
│   │       ├── components/      # Reusable UI components
│   │       │   ├── activities/  # Activity feed components
│   │       │   ├── curseWorld.tsx
│   │       │   ├── demonPreview.tsx
│   │       │   └── ...
│   │       ├── containers/      # Connected container components
│   │       ├── hooks/           # Custom React hooks
│   │       ├── reducers/        # Redux reducers
│   │       ├── services/        # API service layer
│   │       ├── types/           # TypeScript type definitions
│   │       ├── utils.ts         # Utility functions
│   │       ├── store.ts         # Redux store configuration
│   │       └── navigation.tsx   # React Navigation setup
│   │
│   └── backend/                 # Node.js backend server
│       ├── api/                 # API modules
│       │   ├── arGis/           # AR/GIS entity management
│       │   │   ├── model/       # Mongoose schema
│       │   │   │   ├── ar-gis-model.js
│       │   │   │   └── ar-gis-types.js
│       │   │   ├── dao/         # Data access layer
│       │   │   ├── controller/  # Request handlers
│       │   │   ├── routes/      # Express routes
│       │   │   └── arGisLibrary.js  # Business logic
│       │   ├── users/           # User management
│       │   │   ├── model/       # User schema
│       │   │   ├── dao/
│       │   │   ├── controller/
│       │   │   └── routes/
│       │   ├── activity/        # Activity feed
│       │   │   ├── model/       # Activity schema
│       │   │   ├── dao/
│       │   │   ├── controller/
│       │   │   └── routes/
│       │   ├── admin/           # Admin utilities
│       │   │   ├── routes.js
│       │   │   └── admin-controller.js
│       │   ├── library/         # Shared utilities
│       │   │   ├── socket.js    # Socket.IO setup
│       │   │   └── notifications.js
│       │   ├── middleware/      # Express middleware
│       │   │   ├── auth.js      # JWT authentication
│       │   │   └── rateLimiter.js
│       │   ├── config.js        # Configuration loader
│       │   ├── database.js      # MongoDB connection
│       │   ├── point.js         # GeoJSON Point schema
│       │   └── router.js        # Route aggregator
│       ├── public/              # Static files
│       │   ├── index.html       # Landing page
│       │   ├── privacyPolicy.html
│       │   ├── termsOfService.html
│       │   ├── images/
│       │   ├── css/
│       │   └── fonts/
│       ├── test/                # Jest tests
│       ├── index.js             # Server entry point
│       └── package.json
│
└── README.md                    # This file

📝 API Endpoints

Authentication

• POST /api/users - User signup (IP rate limited)
• PUT /api/users - User signin (IP rate limited)
• POST /api/resetPassword - Request password reset email

User Management

• PATCH /api/users - Search for users (auth required)
• PUT /api/user - Update user profile (auth required)
• POST /api/user - Increment user stat field (auth required)
• PATCH /api/user - Use level-up point (auth required)
• POST /api/leaderboard - Get leaderboard (auth required)
• POST /api/refreshCredits - Attempt credit refresh (auth required)

AR/GIS Entities (Curses)

• POST /api/argis - Place new curse (auth required)
• PUT /api/argis - Get curses near location (auth required)
• PATCH /api/argis - Destroy/kill a curse (auth required)
• POST /api/argisLocate - Get curses within radius (auth required)
• PUT /api/yourArgis - Get your placed curses (auth required)
• PATCH /api/yourArgis - Get curses placed against you (auth required)
• POST /api/argisLocations - Check curse existence at locations (auth required)
• POST /api/argisUsers - Check curses on users (auth required)

Activity Feed

• (Activity routes exist - check activity/routes/activity-routes.js)

Admin

• GET /api/admin - Get server hostname (IP rate limited)
• POST /api/admin - Send test push notification (IP rate limited)
• POST /api/support - Submit support request (CORS enabled)
• POST /api/contact - Submit contact form (CORS enabled)
• POST /api/subscribe - Newsletter subscription (CORS enabled)

Static Pages

• GET / - Landing page
• GET /privacyPolicy.html - Privacy policy
• GET /termsOfService.html - Terms of service

🔌 Socket.IO Events

Client → Server

• subscribeUser - Subscribe to user-specific events (join room)
• unsubscribeUser - Unsubscribe from user events (leave room)

Server → Client

• userCursed - Notification when a curse is placed on the user
  • Payload: ArGis entity object
• creditRateChanged - Notification when credit rate changes
  • Payload: { newCreditRate: number }

🗄️ Database Schema

User Model

{
  _id: String (shortid),
  username: String (3-20 chars, unique, lowercase),
  email: String (optional, ≤100 chars),
  password: String (bcrypt hashed),
  experience: Number (default: 0),
  energyRegenerationFactor: Number (default: 1),
  weaponRegenerationFactor: Number (default: 1),
  totalEnergyFactor: Number (default: 1),
  level: Number (default: 10),
  levelUps: Number (default: 10),
  energyTimeToTotal: Number,
  curseCredits: Number (default: 35),
  creditsEarnedSession: Number (default: 0),
  lastCreditRefresh: Date,
  deviceToken: String (for push notifications, ≤150 chars),
  lastLocation: Point (GeoJSON),
  tutorialWatched: Boolean (default: false),
  createdAt: Date,
  updatedAt: Date
}

ArGis Model (Curse Entity)

{
  _id: String (shortid),
  type: String ('location' | 'user'),  // Curse target type
  arType: String,  // Visual representation type
  createdBy: String (User ref),
  createdByUsername: String,
  anonymous: Boolean (default: false),
  locationName: String,  // For location-based curses
  locationId: String,    // Location identifier
  geometry: Point (GeoJSON),  // GPS coordinates
  targetUser: String (User ref),  // For user-targeted curses
  destroyedBy: String (User ref, nullable),
  destroyedDate: Date (nullable),
  createdAt: Date,
  updatedAt: Date
}

Activity Model

{
  _id: String (shortid),
  user: String (User ref, required),  // Actor
  targetUser: String (User ref),       // Target (optional)
  arGis: String (ArGis ref),           // Related curse
  type: String ('friend' | 'destroy' | 'attachlocation' | 'attachuser'),
  createdAt: Date,
  updatedAt: Date
}

• Unique compound index on: (user, targetUser, type, arGis)

🎮 Detailed Gameplay Mechanics

Curse Placement

1. Player selects location on map OR targets specific user
2. System checks if curse already exists at that location/target
3. Player spends curse credits (cost varies by curse type)
4. Curse entity created in database with GPS coordinates
5. Target user receives real-time Socket.IO notification (if user-targeted)
6. Creator's creditsEarnedSession increments by 1

Curse Destruction

1. Player selects enemy curse to destroy
2. System calculates experience reward
3. Experience added to player's total
4. Level-up check: XP >= (level^1.2) * 30
5. If level up: XP resets to 0, level increments, levelUps += 1
6. Curse marked as destroyed in database
7. Creator's creditsEarnedSession decrements by 1
8. Push notification sent to curse creator (if device token exists)

Resource Management

• Curse Credits: Primary currency, used to place curses
• Energy: Time-based resource for actions (regeneration factor upgradeable)
• Weapons: Combat resource (regeneration factor upgradeable)
• Level-Up Points: Spent on permanent stat upgrades

Geospatial Features

• MongoDB GeoJSON Point schema for precise GPS storage
• Geospatial queries for "nearby" curse detection
• Radius-based curse retrieval
• Location-based curse uniqueness checks

🔒 Security & Configuration

Never commit to version control:

• .env files containing credentials
• *.p8, *.p12, *.pem files (Apple certificates)
• API keys or secrets
• Database credentials
• Redis passwords

Required Environment Variables (Backend):

# Server
PORT=2012

# Database
MONGODB_URI=mongodb://localhost:27017/possessed

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_KEY=your-redis-password

# Authentication
JWT_SECRET=your-jwt-secret

# Email (Gmail)
GMAIL_USER=your-email@gmail.com
GMAIL_PASS=your-app-password

# Apple Push Notifications
APN_KEY_ID=your-apn-key-id
APN_TEAM_ID=your-apn-team-id
APN_KEY=path/to/AuthKey.p8

Mobile App Configuration:

• Edit packages/mobile-app/.env with backend API base URL
• Configure Redux store for persistence
• Set up Axios base URL in setupAxios.ts

🛠️ Development

Running Tests

# Backend tests (with MongoDB Memory Server)
cd packages/backend
npm test

# Mobile app tests
cd packages/mobile-app
npm test

Code Quality

# Backend
cd packages/backend
npm run pretty  # Prettier formatting

# Mobile app
cd packages/mobile-app
npm run lint    # ESLint
npm run pretty  # Prettier formatting
npm run tsc     # TypeScript type checking

Debugging

Backend:

• Server logs include Socket.IO connection events
• Redis connection status logged on startup
• MongoDB connection status via Mongoose

Mobile:

• Redux DevTools integration (if configured)
• React Native Debugger compatible
• Console logs for API requests (Axios interceptors in setupAxios.ts)

🌐 Deployment

Backend Deployment

• Designed for Node.js 14.x environments
• Requires MongoDB and Redis instances
• Can be deployed to: Heroku, AWS EC2/Elastic Beanstalk, DigitalOcean, etc.
• Ensure all environment variables are set
• Static files served from public/ directory

Mobile App Deployment

• iOS: Build with Xcode, deploy via App Store Connect
• Android: Build APK/AAB, deploy via Google Play Console
• Configure production API endpoint before build

🌟 Technical Highlights

What makes this project interesting:

1. Geospatial Gaming: MongoDB GeoJSON integration for real-world location-based gameplay
2. Dual Curse Types: Innovative location AND user-targeted curse system
3. Real-time Multiplayer: Socket.IO with Redis adapter for horizontal scaling
4. Strategic Resource Management: Multi-layered progression (XP, levels, credits, energy, weapons)
5. Rate Limiting: Redis-based IP and token rate limiting for API security
6. Push Notification Integration: APN for real-time mobile alerts
7. Persistent State: Redux Persist for offline capability
8. Security: JWT auth + bcrypt password hashing + middleware protection
9. Scalable Architecture: Redis pub/sub for Socket.IO across multiple servers

📝 License

Private - All rights reserved

---

Note: This is a portfolio project showcasing full-stack mobile game development, real-time multiplayer systems, geospatial programming, and scalable backend architecture. The production deployment and API keys have been removed for security. The game's tagline "Possess The World" and branding "Brought to you by Beezlebuddy 😇" reflect its playful demonic theme.