1. INTRODUCTION

1.1 Purpose of this Manual

This user manual provides comprehensive documentation for the Decentralized Physical Infrastructure Network Geographic Information System (DePIN GIS) that will be implemented for Pacific Island utilities. It serves as a complete reference for staff members at Kosrae Utilities Authority (KUA), Pohnpei Utilities Corporation (PUC), and Yap State Public Service Corporation (YSPSC).

1.2 System Overview

The AI-Powered DePIN GIS system will combine blockchain technology with geographic information systems and AI-Agents to create a robust platform for managing utility infrastructure. The future system will provide:

• Secure infrastructure asset registration and tracking
• Decentralized maintenance scheduling and reporting
• Enhanced field data collection through mobile devices
• Web-based mapping visualization
• Optimized reward system for maintenance activities
• Transparent record-keeping through blockchain

1.3 Key Features

• Infrastructure Registry: Enhanced digital registry of all utility assets with spatial information
• Maintenance Scheduler: Smart contract-based maintenance planning system
• Field Data Collection: Mobile applications for on-site data gathering
• Map Visualization: Web interface with interactive maps and data layers
• Blockchain Security: Immutable record-keeping for all system activities
• Integration Capability: Connection with existing utility systems

2. SYSTEM ARCHITECTURE

2.1 Component Overview

The AI-Powered DePIN GIS system will consist of the following AI-enhanced components:

2.2 Smart Contracts

The system will rely on four core smart contracts:

1. UserManager: User authentication and role-based permissions
2. InfrastructureRegistry: Records of all physical infrastructure assets
3. MaintenanceScheduler: Maintenance tasks, schedules, and assignments
4. RewardManager: Incentives for completed tasks and contributions

2.3 Data Flow

Data flows through the system as follows:

1. Field staff collect data using QField mobile app
2. Data is synchronized to QGIS Cloud
3. Web interface displays infrastructure data from QGIS Cloud
4. Smart contracts record activities on the blockchain
5. Analytics and reports are generated from combined data sources

3. INSTALLATION & SETUP

3.1 System Requirements

3.2 Backend Installation

3.2.1 Installing Dependencies

# Update system
sudo apt update && sudo apt upgrade -y

# Install Node.js and npm
sudo apt install nodejs npm

# Install Git
sudo apt install git

# Install Foundry for blockchain development
curl -L https://foundry.paradigm.xyz | bash
foundryup

3.2.2 Clone Repository

# Clone the repository
git clone https://github.com/Pasifika-Web3-Tech-Hub/utility-DePIN-gis.git
cd utility-DePIN-gis

# Install dependencies
npm install

3.2.3 Configure Environment

Create a .env file in the project root:

# Blockchain Configuration
RPC_URL=http://localhost:8545
PRIVATE_KEY=your_private_key_here

# Map Providers
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
VITE_MAPBOX_API_KEY=your_mapbox_api_key_here

# Development settings
VITE_APP_ENV=development

3.3 Foundry Installation

Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust. It's required for smart contract development and deployment in the DePIN GIS system.

3.3.1 Install Foundry on Ubuntu

Run the following commands to install Foundry:

# Download and run the Foundry installer
curl -L https://foundry.paradigm.xyz | bash

# Restart your terminal or run:
source ~/.bashrc

# Install the latest version of Foundry
foundryup

3.3.2 Verify Installation

Verify that Foundry is installed correctly:

# Check Foundry version
forge --version
cast --version
anvil --version

You should see version information for each tool. Foundry includes:

• Forge: Ethereum testing framework (like Truffle, Hardhat)
• Cast: Swiss army knife for interacting with EVM smart contracts
• Anvil: Local Ethereum node (like Ganache)
• Chisel: Fast, utilitarian, and verbose solidity REPL

3.4 Windsurf Installation

Windsurf is an AI-powered IDE that provides intelligent code completion and development assistance. It's highly recommended for developing the DePIN GIS system.

3.4.1 Install Windsurf on Ubuntu

Download and install Windsurf using the following methods:

Method 1: Direct Download

# Download the latest Windsurf .deb package
wget https://windsurf-stable.codeiumdata.com/linux-deb/x64/stable -O windsurf.deb

# Install the package
sudo dpkg -i windsurf.deb

# Fix any dependency issues if they occur
sudo apt-get install -f

Method 2: Using Snap (Alternative)

# Install via Snap (if available)
sudo snap install windsurf --classic

3.4.2 Launch Windsurf

After installation, you can launch Windsurf:

# Launch from terminal
windsurf

# Or launch from applications menu
# Search for "Windsurf" in your applications

3.4.3 Configure Windsurf for DePIN GIS Development

Once Windsurf is installed:

1. Open your DePIN GIS project folder in Windsurf
2. Install recommended extensions for Solidity and React development
3. Configure the integrated terminal to use your development environment
4. Set up Git integration for version control

3.5 Smart Contract Deployment

3.5.1 Introduction to Smart Contracts with Solidity

Smart contracts are self-executing contracts with the terms of the agreement directly written into code. For the DePIN GIS system, smart contracts manage infrastructure data, maintenance schedules, and reward distribution on the blockchain.

What are Smart Contracts?

Smart contracts are programs that run on blockchain networks like Ethereum. They automatically execute when predetermined conditions are met, without requiring intermediaries. In our DePIN GIS system, smart contracts:

• Store Infrastructure Data: Immutable records of utility assets
• Manage Permissions: Control who can access and modify data
• Automate Processes: Trigger maintenance schedules and reward payments
• Ensure Transparency: All transactions are publicly verifiable

Solidity Programming Language

Solidity is the primary programming language for writing smart contracts on Ethereum and EVM-compatible networks. Here's a simple example of a smart contract structure:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract InfrastructureRegistry {
    // State variables
    mapping(uint256 => Asset) public assets;
    uint256 public assetCount;
    
    // Struct to represent an infrastructure asset
    struct Asset {
        uint256 id;
        string name;
        string location;
        address owner;
        uint256 lastMaintenance;
    }
    
    // Events for logging
    event AssetRegistered(uint256 indexed id, string name);
    
    // Function to register new asset
    function registerAsset(string memory _name, string memory _location) public {
        assetCount++;
        assets[assetCount] = Asset(assetCount, _name, _location, msg.sender, block.timestamp);
        emit AssetRegistered(assetCount, _name);
    }
}

Key Solidity Concepts for DePIN GIS

3.5.2 DePIN GIS Smart Contract Architecture

Our system uses four main smart contracts working together:

1. UserManager.sol: Handles authentication and role-based permissions
2. InfrastructureRegistry.sol: Stores and manages utility asset data
3. MaintenanceScheduler.sol: Automates maintenance task assignments
4. RewardManager.sol: Distributes tokens for completed work

3.5.3 Deployment Process

Now let's deploy the smart contracts to your local development environment:

# Start local blockchain (for development)
npm run anvil

# In a new terminal, deploy contracts
npm run deploy:local

The deployment process will output contract addresses to deployed_addresses.json.

3.5.4 Verifying Deployment

After deployment, verify your contracts are working:

# Check deployed contracts
cast call [CONTRACT_ADDRESS] "name()" --rpc-url http://localhost:8545

# View deployment details
cat deployed_addresses.json

3.6 Frontend Configuration

# Navigate to frontend directory
cd frontend

# Install frontend dependencies
npm install

# Create environment file from example
cp .env.example .env

# Edit .env file with appropriate values
nano .env

Update the .env file with appropriate values for your map providers and blockchain RPC URL.

3.7 Starting the Application

# Start the frontend application
npm run dev

The application will be available at http://localhost:3000

4. USER INTERFACE NAVIGATION

4.1 Login and Authentication

1. Access the application at your organization's configured URL
2. Use your assigned login credentials provided by your system administrator
3. If your account is registered, you will be authenticated automatically
4. For new users, contact your system administrator to create your account

4.2 Dashboard Overview

The main dashboard consists of:

1. Navigation Menu: Access different sections of the application
2. Summary Statistics: Overview of system status
3. Recent Activity: Latest actions in the system
4. Quick Actions: Common tasks for quick access

4.3 Main Navigation Sections

• Dashboard: System overview and statistics
• Map View: Interactive map with infrastructure layers
• Data Layers: Manage and view GIS data layers
• Infrastructure: Asset registry and management
• Maintenance: Schedule and track maintenance tasks
• Rewards: View and claim rewards for completed work
• Admin: System administration (admin users only)

4.4 User Roles and Permissions

5. BLOCKCHAIN INTEGRATION

5.1 System Authentication

The DePIN GIS system uses secure authentication methods to ensure authorized access to utility data and infrastructure management.

5.2 Data Recording

When performing actions that modify system data:

1. The system will prompt for action confirmation
2. Review the data changes to be recorded
3. Confirm the action to proceed
4. Wait for system confirmation
5. The interface will update once the data is recorded

6. QGIS INSTALLATION & SETUP

6.1 QGIS Desktop Installation on Ubuntu 24.04.3 LTS

QGIS (Quantum Geographic Information System) is the core desktop GIS application for the DePIN system. Follow these steps to install QGIS on Ubuntu 24.04.3 LTS (Noble Numbat).

6.1.1 Official QGIS Repository Installation (Recommended)

For the latest stable QGIS version on Ubuntu 24.04.3 LTS, use the official QGIS repository:

# Add QGIS repository signing key
sudo mkdir -m755 -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/qgis-archive-keyring.gpg https://download.qgis.org/downloads/qgis-archive-keyring.gpg

# Add QGIS repository for Ubuntu 24.04 LTS (Noble)
echo "deb [signed-by=/etc/apt/keyrings/qgis-archive-keyring.gpg] https://qgis.org/ubuntu noble main" | sudo tee /etc/apt/sources.list.d/qgis.list

# Update package list
sudo apt update

# Install QGIS with essential plugins
sudo apt install qgis qgis-plugin-grass qgis-server

# Verify installation
qgis --version

6.1.2 Ubuntu Default Repository Installation (Alternative)

For a simpler installation using Ubuntu's default repositories (may be an older version):

# Update package list
sudo apt update

# Install QGIS from Ubuntu repositories
sudo apt install qgis qgis-plugin-grass

# Install additional useful packages
sudo apt install python3-qgis qgis-providers

# Verify installation
qgis --version

6.1.3 Post-Installation Setup

After installation, perform these initial setup steps:

# Create QGIS configuration directory
mkdir -p ~/.local/share/QGIS/QGIS3/profiles/default

# Set proper permissions
chmod 755 ~/.local/share/QGIS

# Launch QGIS for first-time setup
qgis &

6.2 QGIS Configuration for DePIN

After installation, configure QGIS for optimal use with the DePIN GIS system:

6.2.1 Essential Plugins

Install these plugins via Plugins → Manage and Install Plugins:

• QuickMapServices: For easy access to web map services
• QGIS Cloud Plugin: For seamless cloud integration
• QField Sync: For mobile field data synchronization
• Processing Saga NextGen Provider: Advanced geoprocessing tools
• Point Sampling Tool: For infrastructure data sampling

6.2.2 Project Settings

Configure project settings for Pacific Island utilities:

• CRS (Coordinate Reference System): Use WGS84 (EPSG:4326) for Pacific Island compatibility
• Units: Set to meters for infrastructure measurements
• Precision: Configure decimal places for coordinate display

6.3 System Requirements

7. QGIS CLOUD INTEGRATION

7.1 QGIS Cloud Overview

QGIS Cloud provides web-based GIS services that integrate seamlessly with QGIS Desktop, enabling Pacific Island utilities to share maps and data across their organizations.

7.2 Setting Up QGIS Cloud Account

7.2.1 Account Registration

1. Visit https://qgiscloud.com
2. Click "Sign Up" and choose appropriate plan:
   • Free Plan: 50 MB storage, suitable for small projects
   • Professional Plans: Up to 10 GB storage for utility-scale projects
3. Complete registration with utility organization details
4. Verify email address

7.2.2 QGIS Cloud Plugin Configuration

Configure the QGIS Cloud plugin in QGIS Desktop:

1. Install QGIS Cloud plugin from Plugin Manager
2. Go to Web → QGIS Cloud → Login
3. Enter your QGIS Cloud credentials
4. Test connection

7.3 Publishing Maps to QGIS Cloud

7.3.1 Preparing Your Project

Before publishing, ensure your project is cloud-ready:

• Use relative paths for data sources
• Optimize layer styling for web display
• Set appropriate scale-dependent visibility
• Configure popup templates for feature information

7.3.2 Publishing Process

1. Open your DePIN GIS project in QGIS
2. Go to Web → QGIS Cloud → Publish Map
3. Configure publication settings:
   • Map title and description
   • Access permissions (public/private)
   • Layer visibility settings
4. Click "Publish" and wait for upload completion
5. Access your published map via the provided URL

7.4 Managing Cloud Data

7.4.1 Data Upload

Upload infrastructure data to QGIS Cloud:

• Vector Data: Shapefiles, GeoJSON, KML
• Raster Data: GeoTIFF, PNG with world files
• Database: PostGIS connections

7.4.2 Data Synchronization

Keep local and cloud data synchronized:

1. Use QGIS Cloud plugin sync features
2. Set up automatic sync schedules
3. Monitor sync status and resolve conflicts
4. Maintain data backup procedures

7.5 Web Map Features

QGIS Cloud web maps provide essential features for Pacific Island utilities:

• Interactive Maps: Pan, zoom, and query infrastructure features
• Layer Control: Toggle visibility of different utility layers
• Feature Information: Click features to view detailed attributes
• Measurement Tools: Measure distances and areas
• Print/Export: Generate maps for reports and documentation
• Mobile Responsive: Access maps on tablets and smartphones

8. QFIELD MOBILE APPLICATION

8.1 QField Overview

QField is the mobile companion app for QGIS, designed for field data collection and infrastructure surveying. It's essential for Pacific Island utility field operations.

8.2 QField Installation

8.2.1 Android Installation

1. Open Google Play Store on your Android device
2. Search for "QField for QGIS"
3. Install the app (free version available)
4. Grant necessary permissions:
   • Location access (GPS)
   • Camera access (for photos)
   • Storage access (for data)

8.2.2 iOS Installation

1. Open App Store on your iOS device
2. Search for "QField for QGIS"
3. Install the app
4. Configure location and camera permissions in iOS Settings

8.3 Project Setup for Field Work

8.3.1 Preparing QGIS Project

Configure your QGIS Desktop project for mobile field work:

1. Create or open your DePIN infrastructure project
2. Install QField Sync plugin in QGIS Desktop
3. Configure layers for field editing:
   • Set layer editing capabilities
   • Configure attribute forms
   • Set up photo attachments
   • Define GPS accuracy requirements
4. Package project for QField via Plugins → QField Sync → Package for QField

8.3.2 Transferring Projects to Mobile Device

Transfer packaged projects to your mobile device:

• USB Transfer: Copy project folder to device storage
• Cloud Sync: Use QFieldCloud for automatic synchronization
• Network Share: Access projects from network storage

8.4 Field Data Collection

8.4.1 Basic Navigation

Essential QField navigation for utility field work:

• Map Navigation: Pan, zoom, and rotate the map
• GPS Positioning: Enable GPS to show current location
• Layer Management: Toggle layer visibility
• Feature Selection: Tap features to view/edit attributes

8.4.2 Adding New Infrastructure Features

1. Select the appropriate layer (e.g., power poles, water pipes)
2. Tap the "+" button to add new feature
3. Position the feature using GPS or manual placement
4. Fill in attribute form:
   • Asset ID and type
   • Condition assessment
   • Installation date
   • Technical specifications
5. Attach photos of the infrastructure
6. Save the feature

8.4.3 Photo Documentation

Comprehensive photo documentation for infrastructure assets:

• Multiple Angles: Capture different views of assets
• Condition Details: Document damage, wear, or maintenance needs
• Context Photos: Show asset location and surroundings
• GPS Geotagging: Automatically embed location in photos

8.5 Data Synchronization

8.5.1 Sync with QGIS Desktop

Synchronize field data back to QGIS Desktop:

1. Connect mobile device to computer
2. Copy updated project files from device
3. Open QGIS Desktop and load updated project
4. Use QField Sync plugin to import changes
5. Review and validate field data
6. Publish updates to QGIS Cloud

8.5.2 QFieldCloud Integration

For real-time synchronization using QFieldCloud:

• Create QFieldCloud account
• Upload projects to cloud
• Configure automatic sync in QField app
• Enable real-time collaboration between field teams

8.6 Best Practices for Pacific Island Field Work

8.6.1 Device Preparation

• Battery Management: Bring portable chargers for extended field work
• Weather Protection: Use waterproof cases for tropical conditions
• Offline Maps: Download base maps for areas with poor connectivity
• Backup Storage: Regularly backup data to prevent loss

8.6.2 Data Quality

• GPS Accuracy: Wait for good GPS signal before recording positions
• Attribute Completeness: Fill all required fields
• Photo Quality: Ensure clear, well-lit photos
• Regular Sync: Synchronize data frequently to prevent loss