Skip to content

chefallan/gobyerknows

BranchesTags

Repository files navigation

GoByerKnows - Web3 Government Infrastructure & Complaints Platform 🚀

A mobile application built with React Native + Expo and powered by Solana blockchain. Citizens report infrastructure damage (roads, public facilities, government establishments) and file complaints (employee conduct, service issues, inefficiency). The community validates reports, and participants earn XPHP tokens for their contributions. All records are permanently stored on the Solana blockchain for immutable transparency, accountability, and auditability. Directly connected to government agencies for action and accountability.

📋 Table of Contents

📊 Feasibility Study

Project Overview

GoByerKnows is a decentralized infrastructure and complaints reporting platform leveraging Solana blockchain and Web3 technology to incentivize community participation in government accountability and public service improvement.

Market Opportunity

Problem Statement

  • Infrastructure damage (roads, public buildings, utilities, government facilities) affects millions globally
  • Employee complaints and service quality issues go unreported or are ignored
  • Current reporting systems are centralized, slow, and lack incentives for participation
  • Citizens have no economic motivation to report issues
  • Government agencies struggle with damage and complaint prioritization
  • Corruption and accountability issues plague public institutions
  • No transparent audit trail for government action

Solution

  • Unified platform for infrastructure damage AND employee complaints
  • Community validation ensures report credibility and prevents fraud
  • Token-based rewards (XPHP) incentivize quality reporting and participation
  • All records permanently stored on Solana blockchain - Reports, comments, votes, and validations cannot be deleted or altered
  • Blockchain-verified transactions ensure transparency and immutability
  • Direct government notifications for accountability and action tracking
  • Public audit trail for all reports, validations, and government resolutions
  • Community voting/rating system for government officials by performance and accountability
  • Decentralized storage ensures data integrity independent of any single authority

Technical Feasibility ✅

Existing Technology Stack

Component Status Notes
React Native/Expo ✅ Mature Production-ready, 100k+ apps
Solana Blockchain ✅ Live 400+ TPS, $3-10 per transaction
Web3.js SDK ✅ Stable Official Solana library
Mobile APIs ✅ Available Camera, location, storage
AI/ML ✅ Feasible OpenAI Vision, custom models
Email Services ✅ Available SendGrid, Twilio

Development Timeline

Phase Duration Status
Phase 1: MVP 4-6 weeks ✅ In Progress
- Wallet connection 1 week ✅ Complete
- Report submission 1 week ✅ Complete
- UI/UX 1 week ✅ Complete
- Testing 2 weeks 🔄 Pending
Phase 2: Core Features 6-8 weeks ⏳ Not Started
- Validation system 2 weeks ⏳ Not Started
- Smart contract 2 weeks ⏳ Not Started
- AI verification 2 weeks ⏳ Not Started
- Testing & audit 2 weeks ⏳ Not Started
Phase 3: Enterprise 4-6 weeks ⏳ Not Started
- Government API 1 week ⏳ Not Started
- Email notifications 1 week ⏳ Not Started
- Token exchange 2 weeks ⏳ Not Started
- Launch prep 2 weeks ⏳ Not Started
TOTAL 14-20 weeks -

Estimated Cost Breakdown

Item Estimate Notes
Development $50k-75k 3-4 engineers, 5-6 months
Smart Contract Audit $10k-20k Essential for mainnet
Infrastructure $5k-10k Servers, databases, APIs
Testing/QA $5k-10k Comprehensive testing
Legal/Compliance $5k-15k Depending on jurisdiction
Marketing $10k-20k Launch and growth
Contingency $10k 10% buffer
TOTAL $95k-160k Typical startup budget

Financial Feasibility ✅

Revenue Models

  1. Government Contracts (Primary)

    • License to municipalities
    • Per-report fee ($0.50-$2.00)
    • Annual subscription ($10k-100k)
    • Estimated revenue: $500k-$2M annually

  2. Token Economics

    • Reporter: 10 XPHP per verified report
    • Validator: 1 XPHP per successful validation
    • Contributor (comment/update): 0.5-1 XPHP per helpful contribution
    • Exchange rate: 1 XPHP = 1 PHP
    • Monthly token cost: $8k-$25k for rewards (includes contributors)

  3. B2B Services

    • API access for contractors
    • Premium analytics dashboard
    • White-label solutions

Token Economics (XPHP)

Total Supply: Infinite (Algorithmic Supply)
Exchange Mechanism: Treasury-Backed (1:1 PHP/XPHP ratio)

Treasury Model:
  - Backing: 100% collateralized by PHP reserves
  - Minting: 1 PHP deposited = 1 XPHP minted
  - Burning: 1 XPHP redeemed = 1 PHP withdrawn
  - Governance: Treasury managed by DAO/Foundation

Government Partnership Budget (Monthly Operations):
  - Government allocation per month: 15M-20M PHP
  - Reporter rewards: ~5M-10M XPHP (100k-200k reports/month)
  - Validator rewards: ~1M-2M XPHP (100k validations/month)
  - Contributor rewards: ~0.5M-1M XPHP (comments, updates, evidence/photos)
  - Administrative & infrastructure: ~2M-3M XPHP
  - Platform development & maintenance: ~2M-5M PHP
  - Total monthly budget: 15M-20M PHP from government

Funding Model:
  - Primary: Government infrastructure budget allocation
  - Secondary: Municipal government payments per report verified
  - Tertiary: B2B API subscriptions and premium services
  - Flow: Government deposits PHP → Mints equivalent XPHP → Distributed as rewards

Market Feasibility ✅

Target Markets

  1. Primary: Philippines (PHP fiat, active government)
  2. Secondary: Southeast Asia (Vietnam, Thailand, Indonesia)
  3. Tertiary: Latin America, Africa (emerging markets)

Addressable Market

  • Population covered: 500M+ people
  • Government budgets for infrastructure: $200B+ annually
  • Potential market share (0.1%): $200M+

Competitive Landscape

  • Waze: Voluntary reporting, no incentives
  • Google Maps: Crowdsourced, centralized
  • Government apps: Low adoption, poor UX
  • Unique advantage: Token incentives + blockchain transparency

Regulatory Feasibility ⚠️

Challenges

  • Crypto regulation varies by country
  • Government data security requirements
  • Privacy concerns (location tracking)
  • Token classification (utility vs. security)

Mitigations

  • Start with Philippines (crypto-friendly)
  • Comply with data protection (PDPA)
  • Use anonymized aggregated data
  • Legal review of token structure
  • Government pilot programs

Technical Risks & Mitigations

Risk Severity Mitigation
Solana network downtime Medium Use fallback RPC, store locally
Smart contract bugs High Professional audit, testnet
User adoption High Incentives, partnerships
Image verification accuracy Medium Human review + AI
Government API integration Medium API spec compliance
Token price volatility Medium Stablecoins, fiat conversion

Success Metrics (Phase 1)

  • ✅ MVP functional and tested
  • ✅ Wallet integration working
  • ✅ Report submission with photos/location
  • ✅ 100+ test users
  • ✅ 50+ verified reports
  • ✅ <2 second transaction time

Success Metrics (Phase 2)

  • Community validation with 80%+ accuracy
  • Smart contract deployed on mainnet
  • AI verification >90% accuracy
  • 1000+ active users
  • 10k+ reports submitted
  • $10k+ in token rewards distributed

Success Metrics (Phase 3)

  • 5+ government partnerships
  • 50k+ users across regions
  • 100k+ verified reports
  • 1M+ XPHP tokens distributed
  • Exchange rate: 1 XPHP = 1 PHP
  • $1M+ annual revenue

Conclusion

Overall Feasibility: ✅ HIGHLY FEASIBLE

Key Strengths

  • ✅ Clear problem with large market
  • ✅ Proven technology stack
  • ✅ Multiple revenue streams
  • ✅ Strong incentive mechanism
  • ✅ Scalable architecture

Key Risks

  • ⚠️ Regulatory uncertainty
  • ⚠️ User adoption
  • ⚠️ Token economics complexity
  • ⚠️ Government cooperation

Recommendation

  • Proceed with MVP development
  • Focus on Philippines market first
  • Build government partnerships early
  • Plan for regulatory compliance
  • Monitor token economics closely

For the Fastest Setup (5 minutes)

# 1. Navigate to project
cd gobyerknows

# 2. Install dependencies
npm install

# 3. Create environment file
# Windows PowerShell:
@"
EXPO_PUBLIC_API_URL=http://localhost:3000/api
EXPO_PUBLIC_SOLANA_NETWORK=devnet
EXPO_PUBLIC_SOLANA_RPC=https://api.devnet.solana.com
"@ | Out-File -FilePath .env.local -Encoding UTF8

# Mac/Linux:
cat > .env.local << EOF
EXPO_PUBLIC_API_URL=http://localhost:3000/api
EXPO_PUBLIC_SOLANA_NETWORK=devnet
EXPO_PUBLIC_SOLANA_RPC=https://api.devnet.solana.com
EOF

# 4. Start development server
npm start

# 5. Open on phone/emulator
# - Scan QR code with Expo Go (phone)
# - Press 'a' for Android emulator
# - Press 'w' for web browser
# - Press 'i' for iOS simulator (macOS only)

📋 Prerequisites

Before you start, make sure you have:

Required

For Mobile Testing

  • Expo Go app (on your phone) - Free from App Store or Google Play
  • Android Studio (optional, for Android emulator) - Download
  • Xcode (optional, for iOS on macOS) - App Store

Verify Installation

node --version      # Should be 18.0.0 or higher
npm --version       # Should be 9.0.0 or higher
git --version       # Should be installed

💾 Installation

Step 1: Clone or Create Project

# Option A: Clone from GitHub
git clone https://github.com/yourusername/gobyerknows.git
cd gobyerknows

# Option B: Already have the project
cd gobyerknows

Step 2: Install Dependencies

npm install

This may take 2-5 minutes and downloads all required packages including:

  • React Native
  • Expo
  • Solana Web3.js
  • Navigation libraries
  • Camera & location services

Step 3: Create Environment File

Create .env.local in the project root with:

EXPO_PUBLIC_API_URL=http://localhost:3000/api
EXPO_PUBLIC_SOLANA_NETWORK=devnet
EXPO_PUBLIC_SOLANA_RPC=https://api.devnet.solana.com

Step 4: Verify Setup

npm install -g expo-cli    # Optional but recommended
expo --version             # Should show version number

🎮 Running the App

Option 1: Expo Go (Easiest - Your Phone) 📱

  1. Download Expo Go from App Store or Google Play
  2. Run npm start
  3. Open Expo Go on your phone
  4. Scan the QR code from terminal
  5. App opens on your phone!

Option 2: Android Emulator 🤖

# Prerequisites: Android Studio installed

# Run:
npm run android
# or press 'a' in terminal after npm start

Option 3: Web Browser 🌐

npm run web
# or press 'w' in terminal after npm start

# Opens at http://localhost:8081

Option 4: iOS Simulator 🍎 (macOS Only)

npm run ios
# or press 'i' in terminal after npm start

Terminal Commands (While npm start is running)

Key Action
a Android emulator
i iOS simulator (macOS)
w Web browser
r Reload app
m Toggle menu
j Open debugger
o Open in code editor
? Show all commands
Ctrl+C Stop dev server

📁 Project Structure

gobyerknows/
├── src/
│   ├── screens/
│   │   ├── HomeScreen.tsx       # Home page with overview
│   │   └── ReportScreen.tsx     # Report submission form
│   ├── components/
│   │   └── WalletButton.tsx     # Wallet connection button
│   ├── services/
│   │   ├── solanaService.ts     # Solana blockchain functions
│   │   └── reportService.ts     # API calls for reports
│   ├── context/
│   │   └── SolanaContext.tsx    # Wallet state management
│   └── utils/                   # Helper functions
├── assets/                      # Images and icons
├── App.tsx                      # Main entry point
├── app.json                     # Expo configuration
├── tsconfig.json                # TypeScript settings
├── package.json                 # Dependencies
├── .env.local                   # Environment variables
└── README.md                    # This file

✨ Features

Current Features ✅

  • Wallet Connection - Connect Solana wallet (devnet/mainnet)
  • Report Submission - Capture photos with camera + location tagging for any government issue
  • Report Types Supported:
    • Infrastructure damage (roads, potholes, flooding, public buildings)
    • Government establishment complaints (service quality, maintenance issues)
    • Employee conduct complaints (unprofessional behavior, corruption)
    • General government service issues
  • Report Details - Add title, description, and categorization for each report
  • Public Report Feed - All reports are public and visible to all users
  • Community Comments & Updates - Anyone can comment, add photos, or provide updates on any report
  • Contributor Rewards - Earn XPHP tokens (0.5-1 XPHP) for helpful comments and evidence/photo contributions
  • Solana Blockchain Storage - All records permanently stored on Solana:
    • Reports cannot be deleted or modified after submission
    • Complete audit trail of all comments, votes, and validations
    • Immutable proof of government official actions and response times
    • Publicly verifiable on blockchain explorers
  • Government Official Voting - Community can vote/rate government officials:
    • By barangay, municipality, city, and nationwide
    • Rate officials based on performance and accountability
    • View official profiles with voting records and citizen feedback
    • Transparent public rankings of officials
    • All voting records stored immutably on blockchain
  • Responsive UI - Works on phones, tablets, and web
  • TypeScript - Full type safety

Coming Soon 🔄

  • Community Validation - Citizens validate reports from other users (earn 1 XPHP per validation)
  • Smart Contract - XPHP token minting and distribution on Solana
  • AI Verification - Detect duplicate submissions and validate damage
  • Government Notifications - Auto-email government agencies assigned to each report type
  • Contributor Leaderboard - Rank users by contribution value (comments, updates, photos)
  • Official Performance Dashboard - Track government official ratings and citizen satisfaction scores
  • XPHP to PHP Exchange - Convert tokens to Philippine Pesos
  • Accountability Dashboard - Track government response times and resolutions
  • Report Categories - Pre-defined categories for roads, buildings, utilities, employee conduct, services
  • Upvoting System - Community upvotes on comments (can increase XPHP rewards for quality contributions)
  • Geographic Voting - Vote/rate officials at barangay, municipality, city, and national levels
  • Official Profiles - Public profiles showing voting history, citizen feedback, and response rates

🛠️ Tech Stack

Frontend

  • React Native - Cross-platform mobile framework
  • Expo - Development platform and deployment
  • TypeScript - Type-safe JavaScript
  • React Navigation - Screen navigation

Blockchain & Storage

  • Solana Network - Primary blockchain for all record storage
    • Reports, comments, validations, votes stored as immutable transactions
    • Publicly verifiable on Solana blockchain explorers
    • Devnet for testing, Mainnet for production
  • Solana Web3.js - Blockchain interaction and account management
  • SPL Token (XPHP) - Token rewards for participation
  • Anchor Framework - Smart contract development (when ready)

Native APIs

  • expo-camera - Camera capture
  • expo-location - GPS location
  • expo-image-picker - Photo selection
  • @react-native-async-storage - Local storage

⚙️ Configuration

Environment Variables (.env.local)

# API Endpoint
EXPO_PUBLIC_API_URL=http://localhost:3000/api

# Solana Network (devnet, testnet, or mainnet-beta)
EXPO_PUBLIC_SOLANA_NETWORK=devnet

# Solana RPC Endpoint
EXPO_PUBLIC_SOLANA_RPC=https://api.devnet.solana.com

App Configuration (app.json)

Key settings:

  • name: "GoByerKnows"
  • slug: "gobyerknows"
  • version: "1.0.0"
  • plugins: Camera and Location permissions

🔗 Using Your Wallet

Connect a Solana Wallet

  1. Click "Connect Wallet" button
  2. Either:
    • Paste your Solana wallet address, or
    • Click "Generate Test Wallet" for development

Get Test SOL (Free)

  1. Go to faucet.solana.com
  2. Paste your wallet address
  3. Receive 2 free SOL

Create a Real Wallet

🐛 Troubleshooting

"Module not found" Error

npm cache clean --force
rm -r node_modules
rm package-lock.json
npm install
npm start

"Port 8081 in use" Error

npm start -- -p 8082

Cannot Scan QR Code

  • Make sure phone and computer are on the same WiFi
  • Try typing the address manually in Expo Go
  • Restart terminal and run npm start again

Camera/Location Permission Denied

  • iOS: Settings → GoByerKnows → Enable permissions
  • Android: App Settings → Permissions → Grant access

App Won't Load on Phone

  • Wait 10-20 seconds for Metro to compile
  • Press r in terminal to reload
  • Restart npm start
  • Check internet connection

Wallet Connection Failed

  • Verify wallet address is valid (44 characters)
  • Use devnet addresses for testing
  • Don't use addresses from other chains (Ethereum, Bitcoin, etc.)

📱 Testing the App

Try These Features:

  1. Connect Wallet

    • Click "Connect Wallet" button
    • Generate test wallet or paste address

  2. Submit Report

    • Click "Submit Report"
    • Take a photo with camera
    • Enable location access
    • Add title and description
    • Click submit

  3. View Status

    • See if wallet is connected (green button)
    • Check terminal for transaction logs

🚀 Development Workflow

Making Changes

  1. Edit files in src/ folder
  2. Save the file
  3. App automatically reloads (5-10 seconds)
  4. See changes on phone/emulator instantly

Common Edits

  • Change colors: Edit StyleSheet in component files
  • Add buttons: Use TouchableOpacity in JSX
  • Change text: Edit strings in Text components
  • Add screens: Create new file in src/screens/

Debugging

  • Check terminal for error messages
  • Press j in terminal to open debugger
  • Use browser DevTools (for web version)
  • Check device logs in Android Studio or Xcode

📦 Package Scripts

npm start       # Start development server
npm run web     # Run in web browser
npm run android # Run on Android emulator
npm run ios     # Run on iOS simulator (macOS)
npm test        # Run tests (if configured)
npm run build   # Build for production

🔒 Security Notes

Important

  • Never commit .env.local to git (added to .gitignore)
  • Keep private keys secure
  • Test wallet addresses only on devnet
  • Use mainnet only for real transactions

📚 Resources

Resource Link
Expo Docs https://docs.expo.dev
React Native https://reactnative.dev
Solana Docs https://solana.com/developers
Web3.js API https://solana-labs.github.io/solana-web3.js/
TypeScript https://www.typescriptlang.org
Node.js https://nodejs.org

🆘 Getting Help

If Something Doesn't Work:

  1. Read the error message - Usually tells you the solution
  2. Check Troubleshooting - See section above
  3. Restart everything: 
    Ctrl+C              # Stop npm start
npm cache clean --force
npm install
npm start
  4. Check prerequisites - Install Node.js 18+ if missing

Common Fixes:

Issue Solution
App won't start npm install then npm start
Port in use npm start -- -p 8082
Module error npm install
Can't connect Check same WiFi + wallet address format
Changes not showing Press r in terminal

📈 Next Steps

After installation works:

  1. ✅ Explore the UI - Test all buttons and features
  2. 📝 Read the code - Look at src/ folder structure
  3. 🎨 Customize - Edit colors, text, and layouts
  4. 🚀 Build features - Add new screens and functionality
  5. 📤 Deploy - Push to GitHub and deploy to app stores

📄 License

MIT

🎉 You're All Set!

Everything you need is installed and ready to go.

Next: Run npm start and start building!

Questions? Check the Troubleshooting section or read the resource links above.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages