Merge branch 'main' into feature/ui-ux-improvements

Author: Wilfred007

.env.example

@@ -1,52 +1,117 @@
-# -----------------------------------------------------------------------------
-# PayD root environment template
-# -----------------------------------------------------------------------------
+# =============================================================================
+# PayD Root Environment Configuration
+# =============================================================================
 # Copy this file to `.env` at the repository root before starting local dev:
 #   cp .env.example .env
 #
-# Notes:
-# - Variables prefixed with `PUBLIC_` / `VITE_` are exposed to the frontend.
-# - Keep secrets out of this root file unless absolutely required for local dev.
-# - Use `backend/.env.example` for backend server credentials and secrets.
+# IMPORTANT NOTES:
+# - Variables prefixed with `PUBLIC_` or `VITE_` are exposed to the frontend
+#   and visible in browser JavaScript. DO NOT put secrets in these variables.
+# - Keep secrets (API keys, tokens) in backend/.env.example instead
+# - This file is for blockchain network config and frontend API routing only
+# - For backend secrets, see: backend/.env.example
+# - Do NOT commit real .env files to version control (add to .gitignore)
 
-# -----------------------------------------------------------------------------
-# Stellar scaffold / CLI runtime settings
-# -----------------------------------------------------------------------------
-# Which scaffold environment profile to use.
-# Allowed examples: development | testing | staging | production
+
+# =============================================================================
+# Stellar CLI & Scaffold Configuration (REQUIRED - build + local stellar network)
+# =============================================================================
+
+# Stellar Scaffold Environment Profile
+# Specifies which SDK environment profile to use for Stellar CLI operations
+# Profiles determine: network, RPC endpoints, contract addresses, signer keys
+# Values: development (local sandbox)
+#         staging (testnet or internal staging network)
+#         production (mainnet)
+#         testing (isolated test environment, resets often)
+# Default: development
+# The SDK reads corresponding config from .stellar/ directory
+# Check: ls .stellar/keys/{profile}/ to see available keys/accounts
 STELLAR_SCAFFOLD_ENV=development
 
-# Where Stellar CLI stores local config (relative path shown for local dev).
-# Use an absolute path in CI if needed.
+# XDG Config Home (Stellar SDK Configuration Directory)
+# Base directory where Stellar CLI stores configuration, keys, and metadata
+# For local dev: use relative path e.g., ".config" → creates ./.config in project root
+# For CI/CD or per-user: use absolute path e.g., "/home/user/.stellar"
+# Recommendation: Use relative path for local dev to keep configs in project
+# The SDK creates subdirectories: keys/{profile}/, contracts/, networks/
+# Important: Add this directory to .gitignore to prevent key leaks
 XDG_CONFIG_HOME=".config"
 
-# -----------------------------------------------------------------------------
-# Frontend network configuration (required for blockchain reads/writes)
-# -----------------------------------------------------------------------------
-# Which Stellar network the frontend should target.
-# Common values: LOCAL, TESTNET, MAINNET
+
+# =============================================================================
+# Frontend Stellar Blockchain Network Configuration (REQUIRED - reads/writes)
+# =============================================================================
+
+# Stellar Network Selection (Frontend Target)
+# Which Stellar network the frontend UI connects to
+# Values: LOCAL (local developer sandbox)
+#         TESTNET (SDF Stellar testnet, free, resets monthly)
+#         MAINNET (production Stellar mainnet, real XLM)
+# Must match the network that VITE_STELLAR_RPC_URL and VITE_STELLAR_HORIZON_URL connect to
+# Mismatches: Would cause transaction failures or rejected signed transactions
+# Default: LOCAL (recommended for local dev with docker-compose up)
+# PUBLIC prefix: Visible in browser frontend (JavaScript). Not a secret.
 PUBLIC_STELLAR_NETWORK="LOCAL"
 
-# Passphrase for the selected network.
-# LOCAL example: "Standalone Network ; February 2017"
-# TESTNET example: "Test SDF Network ; September 2015"
-# MAINNET example: "Public Global Stellar Network ; September 2015"
+# Stellar Network Passphrase (Frontend)
+# Cryptographic string that identifies the specific Stellar network
+# Every transaction signed includes this passphrase; mismatches = invalid tx
+# Must match the actual network being used (see PUBLIC_STELLAR_NETWORK)
+# Current networks:
+#   LOCAL: "Standalone Network ; February 2017" (Stellar dev docker sandbox)
+#   TESTNET: "Test SDF Network ; September 2015" (SDF public testnet)
+#   MAINNET: "Public Global Stellar Network ; September 2015" (SDF mainnet)
+# Important: This is included in transaction signatures; changing it invalidates old signatures
+# PUBLIC prefix: Visible in browser. Not a secret (it's in every transaction anyway).
 PUBLIC_STELLAR_NETWORK_PASSPHRASE="Standalone Network ; February 2017"
 
-# Soroban RPC endpoint used by contract-read/write flows in the frontend.
+# Stellar RPC Endpoint (Soroban Read/Write operations)
+# JSON-RPC endpoint for smart contract reads and transaction submissions
+# Used by: Frontend for contract deployments, function calls, state reads
+# Must be compatible with PUBLIC_STELLAR_NETWORK selection
+# LOCAL: http://localhost:8000/rpc (requires: docker-compose up to run Stellar sandbox)
+# TESTNET: Use a Soroban RPC provider (e.g., https://soroban-testnet-rpc.stellar.org)
+# MAINNET: Use a Soroban RPC provider (e.g., https://soroban-mainnet-rpc.stellar.org)
+# Format: Must include /rpc path for RPC calls
+# PUBLIC prefix: Exposed to frontend JavaScript (localhost is fine for dev)
 PUBLIC_STELLAR_RPC_URL="http://localhost:8000/rpc"
 
-# Horizon endpoint used by frontend transaction/history utilities.
+# Stellar Horizon Endpoint (Transaction history and metadata)
+# REST API endpoint for reading ledger data, accounts, transactions
+# Used by: Frontend for account balance checks, transaction history, fee estimation
+# Must be compatible with PUBLIC_STELLAR_NETWORK selection
+# LOCAL: http://localhost:8000 (Stellar dev sandbox with Horizon on same port)
+# TESTNET: https://horizon-testnet.stellar.org (SDF public API, rate-limited)
+# MAINNET: https://horizon.stellar.org (SDF public API, rate-limited)
+# Format: Just the host:port, no path suffix
+# PUBLIC prefix: Exposed to frontend JavaScript (localhost is fine for dev)
 PUBLIC_STELLAR_HORIZON_URL="http://localhost:8000"
 
-# -----------------------------------------------------------------------------
-# Frontend API + auth routing (required for local full-stack runs)
-# -----------------------------------------------------------------------------
-# Primary API origin used by most frontend service modules.
+
+# =============================================================================
+# Frontend API & Backend Routing (REQUIRED - requests to backend server)
+# =============================================================================
+
+# Primary Backend API Origin
+# The base URL where frontend makes all API requests (auth, users, payroll, etc.)
+# Must exactly match backend's CORS_ORIGIN setting or requests will be blocked
+# Format: http(s)://hostname:port (no trailing slash!)
+# LOCAL: http://localhost:3000 (backend dev server)
+# STAGING: https://api-staging.payd.io
+# PRODUCTION: https://api.payd.io
+# Important: MUST include protocol (http:// or https://) and port if not default
+# VITE_ prefix: Exposed to frontend JavaScript at build time
 VITE_API_URL="http://localhost:3000"
 
-# Optional fallback API origin used by selected modules.
-# Keep aligned with VITE_API_URL unless intentionally split.
+# Fallback/Secondary Backend API Origin
+# Alternative API endpoint for specific modules (if needs differ from main)
+# Usually kept aligned with VITE_API_URL unless intentionally split
+# Format: Same as VITE_API_URL
+# Most modules use VITE_API_URL; only special cases use this fallback
+# Leave aligned with VITE_API_URL unless you have a specific reason to differ
+# Examples of split: analytics API on different domain, legacy endpoint
+# VITE_ prefix: Exposed to frontend JavaScript at build time
 VITE_API_BASE_URL="http://localhost:3000"
 
 # Backend auth endpoint origin used by login callbacks.

.gitattributes

@@ -1,2 +1,8 @@
 Cargo.lock text -merge eol=lf linguist-generated=true -diff
 package-lock.json linguist-generated=true -diff
+
+# Enforce LF line endings for all SQL migration files.
+# This prevents CRLF↔LF drift caused by git's core.autocrlf on Windows,
+# which silently changes the SHA-256 checksum of migration files and triggers
+# "DRIFT DETECTED" failures in the migration runner.
+*.sql text eol=lf

.github/workflows/build.yml

@@ -17,6 +17,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Run documentation tests
+        run: npm run test:docs
       - uses: actions/cache@v3
         with:
           path: |