Skip to content

README.md

Latest commit

 

History

History
239 lines (168 loc) · 9.31 KB

README.md

File metadata and controls

239 lines (168 loc) · 9.31 KB

XAH PAYROLL

DECENTRALIZED HOURLY PAYROLL ON XAHAU

License: MIT Version GitHub Issues GitHub Stars Security Code of Conduct

DOCUMENTATION • FAQ • QUICKSTART • ARCHITECTURE • SECURITY

⭐ SUPPORT THIS PROJECT

IF YOU FIND XAH PAYROLL USEFUL, PLEASE STAR THE REPOSITORY TO HELP OTHERS DISCOVER IT!

⭐ STAR US ON GITHUB

📖 OVERVIEW

XAH PAYROLL IS AN OPEN SOURCE DECENTRALIZED PAYROLL SYSTEM BUILT ON XAHAU (AN XRPL SIDECHAIN).

XAHAU CONTEST JUDGES: FOR QUICK TESTING, PLEASE SEE JUDGES.md

HOW IT WORKS: NGOS/EMPLOYERS CREATE PAYMENT CHANNELS WITH ESCROW FUNDS. WORKERS CLOCK IN/OUT TO TRACK HOURS. EARNINGS ACCUMULATE OFF-CHAIN IN THE DATABASE. WORKERS OR NGOS REQUEST CHANNEL CLOSURE. NGOS APPROVE REQUESTS AND EXECUTE PAYMENTCHANNELCLAIM TRANSACTION. WORKERS RECEIVE ALL ACCUMULATED EARNINGS IN A SINGLE ON-CHAIN PAYMENT. SETTLEDELAY PROTECTS WORKERS DURING CLOSURE TRANSITION.

WHO IT'S FOR: NGOS, EMPLOYERS, AND WORKERS (USING XRPL) WHO NEED TRANSPARENT, DECENTRALIZED WAGE TRACKING WITH MINIMAL TRANSACTION FEES OR THIRD PARTY RISKS.

✨ KEY FEATURES

  • ⏱️ HOURLY WAGE TRACKING: AUTOMATIC CALCULATION OF WORKER EARNINGS WITH CLOCK IN/OUT TRACKING
  • 💰 PAYMENT CHANNELS: SECURE XRPL PAYMENT CHANNELS WITH ON-CHAIN ESCROW PROTECTION
  • 🎯 SINGLE TRANSACTION SETTLEMENT: ALL ACCUMULATED EARNINGS PAID IN ONE TRANSACTION WHEN CHANNEL CLOSES
  • 🏢 MULTI-ORGANIZATION SUPPORT: WORKERS CAN WORK FOR MULTIPLE NGOS WITH SEPARATE PAYMENT CHANNELS
  • 📱 XAMAN WALLET INTEGRATION: MOBILE-FIRST AUTHENTICATION WITH QR CODE SCANNING (DESKTOP) AND DEEP LINKING (MOBILE/DESKTOP) FOR SEAMLESS WALLET CONNECTIVITY
  • 📊 REAL-TIME MONITORING: LIVE TRACKING OF WORK HOURS, ACCUMULATED BALANCE, AND ESCROW STATUS
  • 📄 DATA EXPORT (PDF): WORKERS AND NGOS CAN EXPORT COMPLETE PAYMENT HISTORY, WORK SESSIONS, AND CHANNEL DETAILS AS PDF REPORTS FOR RECORD-KEEPING

🚀 QUICK START

PREREQUISITES

INSTALLATION

# CLONE REPOSITORY
git clone https://github.com/Ghostrayu/xahpayroll.git
cd xahpayroll

# INSTALL ALL DEPENDENCIES (ROOT, FRONTEND, BACKEND)
npm run install:all

# CONFIGURE ENVIRONMENT VARIABLES
cp frontend/.env.example frontend/.env
cp backend/.env.example backend/.env
# EDIT .env FILES WITH YOUR CONFIGURATION

# INITIALIZE DATABASE
cd backend && npm run init-db

# START DEVELOPMENT SERVERS (BACKEND :3001, FRONTEND :3000)
npm run dev

DETAILED SETUP: SEE QUICKSTART.md FOR COMPLETE SETUP INSTRUCTIONS INCLUDING DATABASE CONFIGURATION, NETWORK SWITCHING, AND XAMAN API SETUP.

🏗️ TECH STACK

FRONTEND

  • REACT 18 + TYPESCRIPT + VITE
  • TAILWINDCSS FOR STYLING
  • REACT ROUTER V6 FOR NAVIGATION
  • CONTEXT API FOR STATE MANAGEMENT

BACKEND

  • NODE.JS + EXPRESS
  • POSTGRESQL 14+ DATABASE
  • XRPL SDK FOR LEDGER OPERATIONS
  • JWT AUTHENTICATION

BLOCKCHAIN

  • XAHAU (XRPL SIDECHAIN) INTEGRATION
  • XRPL PAYMENT CHANNELS FOR ESCROW
  • XAMAN WALLET (PRODUCTION)
  • TESTNET AND MAINNET SUPPORT

📚 DOCUMENTATION

CORE DOCUMENTATION

DEPLOYMENT GUIDES

DEVELOPER GUIDES

RELEASE INFORMATION

📸 SCREENSHOTS

NGO DASHBOARD

NGO DASHBOARD MANAGE WORKERS, CREATE PAYMENT CHANNELS, AND MONITOR ACTIVE CHANNELS

NGO ACTIVE PAYMENT CHANNELS

NGO ACTIVE PAYMENT CHANNELS REAL-TIME TRACKING OF ESCROW, ACCUMULATED BALANCES, AND CHANNEL STATUS

PAYMENT CHANNEL CONFIGURATION (1 OF 2)

PAYMENT CHANNEL CONFIG 1 SELECT WORKER, SET HOURLY RATE, AND CONFIGURE JOB DETAILS

PAYMENT CHANNEL CONFIGURATION (2 OF 2)

PAYMENT CHANNEL CONFIG 2 CONFIGURE ESCROW AMOUNT AND PAYMENT CHANNEL SETTINGS

EMPLOYEE WORK SESSIONS

EMPLOYEE WORK SESSIONS WORKERS TRACK HOURS, VIEW ACCUMULATED EARNINGS, AND MANAGE WORK SESSIONS

💻 DEVELOPMENT

COMMON COMMANDS

# START DEVELOPMENT (BOTH SERVERS)
npm run dev

# START SERVERS INDIVIDUALLY
npm run dev:backend   # BACKEND ONLY (:3001)
npm run dev:frontend  # FRONTEND ONLY (:3000)

# BUILD FRONTEND FOR PRODUCTION
npm run build

# RUN LINTER
npm run lint

# TEST DATABASE CONNECTION
cd backend && npm run test:db

# INITIALIZE DATABASE SCHEMA
cd backend && npm run init-db

DEPLOYMENT

# DEPLOY TO PRODUCTION (NETLIFY)
npm run deploy

# DEPLOY PREVIEW
npm run deploy:preview

DEPLOYMENT GUIDES:

🔐 SECURITY

VULNERABILITY REPORTING: EMAIL admin@xahpayroll.xyz WITH DETAILS. DO NOT CREATE PUBLIC GITHUB ISSUES FOR SECURITY VULNERABILITIES.

SECURITY POLICY: SEE SECURITY.md FOR FULL SECURITY POLICY, BEST PRACTICES, AND RESPONSIBLE DISCLOSURE GUIDELINES.

KEY SECURITY FEATURES:

  • NON-CUSTODIAL WALLET INTEGRATION (USERS CONTROL PRIVATE KEYS)
  • PAYMENT CHANNEL ESCROW PROTECTION WITH SETTLEDELAY
  • AUTOMATED DEPENDENCY VULNERABILITY SCANNING
  • DATABASE ENCRYPTION AND SECURE SESSION MANAGEMENT

📄 LICENSE

THIS PROJECT IS LICENSED UNDER THE MIT LICENSE - SEE LICENSE FILE FOR DETAILS.

DEPENDENCIES: ALL 368 PRODUCTION DEPENDENCIES USE PERMISSIVE LICENSES (MIT, ISC, BSD, APACHE-2.0). NO GPL OR COPYLEFT DEPENDENCIES.

🤝 CONTRIBUTING

WE WELCOME CONTRIBUTIONS! PLEASE SEE CONTRIBUTING.md FOR:

  • PULL REQUEST PROCESS
  • CODE STYLE GUIDELINES
  • DEVELOPMENT WORKFLOW
  • COMMIT MESSAGE CONVENTIONS

QUICK CONTRIBUTION STEPS:

  1. FORK THE REPOSITORY
  2. CREATE A FEATURE BRANCH (git checkout -b feature/amazing-feature)
  3. COMMIT YOUR CHANGES (git commit -m 'ADD AMAZING FEATURE')
  4. PUSH TO YOUR FORK (git push origin feature/amazing-feature)
  5. OPEN A PULL REQUEST

💬 SUPPORT & CONTACT

GITHUB: https://github.com/Ghostrayu/xahpayroll/issues

  • BUG REPORTS
  • FEATURE REQUESTS
  • TECHNICAL QUESTIONS

CODE OF CONDUCT: CODE_OF_CONDUCT.md

BUILT WITH ❤️ FOR THE XAHAU ECOSYSTEM

GOOD MONEY COLLECTIVE DONATION XRPL ADDRESS: r3pgsajrrWoFaTajo1wBEEvYzL1RAxjXMe

📖 FAQ • ⭐ STAR THIS PROJECT • 🐛 REPORT BUG • 💡 REQUEST FEATURE