1. System Overview

This game is a real-time, competitive, move-to-earn GPS game. Its architecture is designed as a scalable microservices system to ensure a fast, responsive user experience for gameplay, while leveraging the Very Network blockchain for security, trust, and rewards.

High-Level Architecture Diagram

graph TD
    subgraph "User Layer"
        A[Mobile Web App]
    end

    subgraph "Infrastructure"
        LB[Load Balancer]
    end

    subgraph "Backend Microservices"
        API[API Gateway]

        subgraph "Real-Time Services"
            GLS[Game Logic Service]
            WS[WebSocket Service]
        end

        subgraph "Asynchronous Services"
            US[User Service]
            BS[Blockchain Service]
            NS[Notification Service]
        end
    end

    subgraph "Data & Caching Layer"
        DB[(PostgreSQL Database)]
        Cache[(Redis Cache)]
        MQ([Message Queue <br/> e.g., RabbitMQ])
    end

    subgraph "Very Ecosystem (Decentralized)"
        VN[Very Network Blockchain]
        SC[Smart Contract <br/> Scores & Rewards]
        VAPI[Verychat API]
    end

    %% Connections
    A --> LB
    LB --> API

    API -- "HTTP Requests (Login, Profile)" --> US
    API -- "WebSocket Connection" --> WS

    WS -- "Live GPS Data" --> GLS
    GLS -- "Game State Updates" --> WS

    GLS -- "Player Location Data" --> Cache
    GLS -- "Read/Write Leaderboards" --> DB

    US -- "User Profiles, Wallets" --> DB

    GLS -- "Event: Bank Points" --> MQ
    MQ -- "Consume: Bank Points" --> BS

    GLS -- "Event: Line Broken" --> MQ
    MQ -- "Consume: Line Broken" --> NS

    BS -- "Update Score / Distribute Rewards" --> SC
    SC -- "On-Chain Events" --> VN
    NS -- "Send Notification" --> VAPI
    VAPI -- "Push to User" --> A

2. Detailed Component Breakdown

2.1 User Layer: The Mobile App

• Technology: React or Next.js, using the phone's native GPS API (navigator.geolocation).
• Responsibilities:
  1. Render the UI: Display the map (using a library like Leaflet), player position, active lines, points, and leaderboards.
  2. Manage User State: Handle wallet connection to the Very Network via an integrated wallet like Wepin.
  3. GPS Tracking: Continuously fetch the user's latitude and longitude.
  4. Real-time Communication: Establish and maintain a persistent WebSocket connection to our backend to send its own coordinates and receive updates about other players.

2.2 Infrastructure

• Load Balancer: Distributes incoming user traffic across multiple instances of our services to prevent any single server from being overloaded. This ensures the game remains available and fast even with many players.
• API Gateway: Acts as the single, secure front door to our entire backend. It handles initial user authentication and routes requests to the appropriate microservice. For example, a login request goes to the User Service, while a WebSocket connection request goes to the WebSocket Service.

2.3 Backend Microservices

This is the core engine of the game, broken into specialized, independent services.

• WebSocket Service:
  • Purpose: To manage thousands of simultaneous, persistent connections with players.
  • How it works: It receives the constant stream of GPS coordinates from every player and forwards them to the Game Logic Service. It also receives game state updates (like another player's new position or a "line broken" event) from the Game Logic Service and broadcasts them back to the relevant players.
• Game Logic Service (GLS):
  • Purpose: The high-performance brain of the game.
  • How it works:
    1. It receives a stream of player coordinates from the WebSocket Service.
    2. It stores each player's active "line" (a series of coordinates) in the Redis Cache for incredibly fast access.
    3. For every new coordinate received, it performs collision detection: it checks if that point intersects with the active line of any other nearby player stored in Redis.
    4. If a line is broken, it updates the player's state and sends this update back to the WebSocket Service.
    5. When a player hits a checkpoint, it fires a "Bank Points" event into the Message Queue.
    6. It reads from and writes to the PostgreSQL Database for less time-sensitive data like daily leaderboards.
• User Service:
  • Purpose: To handle all user-related data that isn't real-time gameplay.
  • How it works: Manages user registration, login, profiles, and securely stores their Very Network wallet address in the PostgreSQL Database.
• Blockchain Service:
  • Purpose: The only service that is allowed to talk to the Very Network blockchain. It is designed to be slow, patient, and secure.
  • How it works: It listens to the Message Queue for "Bank Points" events. When it receives one, it securely constructs and sends a transaction to our Smart Contract to update the player's on-chain score. It also runs a scheduled job to distribute daily rewards.
• Notification Service:
  • Purpose: To handle social engagement.
  • How it works: It listens to the Message Queue for events like "Line Broken." When it receives one, it makes an API call to the Verychat API to send a push notification to the user's Verychat app.

2.4 Data & Caching Layer

• PostgreSQL Database: Our source of truth for persistent data.