Docs: redesign PayBridge GitHub Pages with professional structure

.github/workflows/docs-pages.yml

@@ -0,0 +1,58 @@
+name: Docs - GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/docs-pages.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install MkDocs Material
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -258,6 +258,9 @@ _UpgradeReport_Files/
 Backup*/
 UpgradeLog*.XML
 UpgradeLog*.htm
+
+# MkDocs build output
+site/
 ServiceFabricBackup/
 *.rptproj.bak
 

README.md

@@ -5,6 +5,9 @@
 </p>
 
 <p align="center">
+  <a href="https://teesofttech.github.io/PayBridge/">
+    <img src="https://img.shields.io/badge/docs-GitHub%20Pages-0f766e" alt="Documentation">
+  </a>
   <a href="https://github.com/teesofttech/PayBridge/releases">
     <img src="https://img.shields.io/github/v/release/teesofttech/PayBridge" alt="Latest Release">
   </a>
@@ -27,6 +30,16 @@
 
 ---
 
+## Documentation Portal
+
+The redesigned docs site is published on GitHub Pages:
+
+- https://teesofttech.github.io/PayBridge/
+
+Use it as the canonical operational guide for setup, security hardening, routing, idempotency, and integration testing.
+
+---
+
 ## 🚀 Features
 
 - **Unified API**: Interact with multiple payment gateways (e.g., Flutterwave, Paystack, Stripe, Korapay, PeachPayments) through a single, consistent interface.

README.nuget.md

@@ -4,6 +4,7 @@
 
 [![NuGet](https://img.shields.io/nuget/v/PayBridge.SDK)](https://www.nuget.org/packages/PayBridge.SDK)
 [![NuGet Downloads](https://img.shields.io/nuget/dt/PayBridge.SDK)](https://www.nuget.org/packages/PayBridge.SDK)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0f766e)](https://teesofttech.github.io/PayBridge/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/teesofttech/PayBridge/blob/master/LICENSE)
 [![GitHub](https://img.shields.io/badge/GitHub-teesofttech%2FPayBridge-blue)](https://github.com/teesofttech/PayBridge)
 

docs/index.md

@@ -0,0 +1,55 @@
+# PayBridge Documentation
+
+<div class="hero">
+  <div class="hero__eyebrow">Production-grade Payment Orchestration for .NET</div>
+  <h1>Build once. Route safely. Operate confidently.</h1>
+  <p>
+    PayBridge gives your team one integration surface for multi-gateway payments,
+    verification, refunds, webhook security, and operational safeguards.
+  </p>
+  <a class="hero__cta" href="quickstart/">Start with Quick Start</a>
+</div>
+
+## What You Get
+
+- Unified gateway abstraction for payment creation, verification, and refund operations.
+- Secure webhook path with signature verification, replay protection, and fail-closed behavior.
+- Deterministic automatic routing with clear configuration validation at startup.
+- Testable architecture with unit and integration workflows aligned to release quality.
+
+## Documentation Paths
+
+### Start Here
+
+- [Quick Start](quickstart.md): Configure, run, and process your first transaction flow.
+- [Automatic Routing](automatic-gateway-routing.md): Understand route selection and fallback behavior.
+- [Payment Idempotency](payment-idempotency.md): Prevent duplicate effects across retries.
+
+### Security Hardening
+
+- [Webhook Security](webhook-security.md): Signature validation contracts and provider-specific expectations.
+- [Webhook Replay Protection](webhook-replay-protection.md): Replay detection strategy and operations notes.
+- [Dependency Security](dependency-security.md): Vulnerability management and CI safeguards.
+- [Credential Rotation](credential-rotation-and-history-purge.md): Incident response and secret hygiene.
+
+### Reliability and Operations
+
+- [Integration Testing](integration-testing.md): Sandbox preflight gates and run interpretation.
+- [Refund Persistence](refund-persistence.md): Durable refund lifecycle handling.
+- [Flutterwave Refunds](flutterwave-refunds.md): Known behavior and current implementation notes.
+
+## Recommended Reading Order
+
+1. Quick Start
+2. Automatic Routing
+3. Webhook Security
+4. Integration Testing
+5. Idempotency and Refund Persistence
+
+## Release Readiness Checklist
+
+- Gateway credentials configured through secure runtime providers.
+- Webhook signatures verified before payload parsing or fulfillment.
+- Idempotency and replay controls active for mutation endpoints.
+- Unit and integration test gates passing in CI.
+- Documentation and package claims aligned with implementation.

docs/quickstart.md

@@ -0,0 +1,58 @@
+# Quick Start
+
+This guide takes you from a clean repository checkout to a secure first payment flow.
+
+## 1. Install and Restore
+
+```bash
+dotnet restore PayBridge.SDK.sln
+dotnet build PayBridge.SDK.sln
+```
+
+## 2. Configure Database Provider
+
+Use one supported provider and supply the connection string from secure sources.
+
+Supported provider values:
+
+- SqlServer (or MSSQL)
+- Npgsql (or PostgreSQL/Postgres)
+- MySql
+
+## 3. Configure Gateway Credentials
+
+Use .NET user-secrets locally and environment variables or managed secret stores in hosted environments.
+
+Example:
+
+```bash
+dotnet user-secrets set "PaymentGatewayConfig:EnabledGateways:0" "Paystack" --project PayBridge.SDK.Example/PayBridge.SDK.Example.csproj
+dotnet user-secrets set "PaymentGatewayConfig:Paystack:SecretKey" "<sandbox-secret>" --project PayBridge.SDK.Example/PayBridge.SDK.Example.csproj
+```
+
+## 4. Register Services
+
+In your startup wiring:
+
+- Register persistence with AddDBRepository
+- Register SDK services with AddPayBridge
+
+## 5. Run Example API
+
+```bash
+dotnet run --project PayBridge.SDK.Example/PayBridge.SDK.Example.csproj
+```
+
+## 6. Process Payment Lifecycle
+
+1. Create payment using an explicit or automatic gateway route.
+2. Redirect customer to checkout URL.
+3. Verify callback/webhook reference through provider verification.
+4. Persist payment status and fulfill order after successful verification.
+
+## 7. Harden Before Production
+
+- Enforce webhook signature verification and replay protection.
+- Require authenticated access for hosted demo/API surfaces.
+- Keep all credentials server-side.
+- Ensure integration tests run against real sandbox credentials.

docs/stylesheets/extra.css

@@ -0,0 +1,51 @@
+:root {
+  --pb-accent: #0f766e;
+  --pb-accent-strong: #115e59;
+  --pb-surface: #f0fdfa;
+}
+
+.md-content h1 {
+  letter-spacing: -0.02em;
+}
+
+.hero {
+  margin: 0.75rem 0 2rem;
+  padding: 1.5rem;
+  border-radius: 1rem;
+  background: linear-gradient(140deg, rgba(15, 118, 110, 0.12), rgba(6, 182, 212, 0.15));
+  border: 1px solid rgba(15, 118, 110, 0.2);
+}
+
+.hero__eyebrow {
+  font-weight: 700;
+  text-transform: uppercase;
+  font-size: 0.72rem;
+  letter-spacing: 0.06em;
+  color: var(--pb-accent-strong);
+  margin-bottom: 0.5rem;
+}
+
+.hero h1 {
+  margin: 0.25rem 0 0.75rem;
+  font-size: clamp(1.5rem, 4vw, 2.35rem);
+  line-height: 1.15;
+}
+
+.hero p {
+  max-width: 62ch;
+  margin: 0 0 1rem;
+}
+
+.hero__cta {
+  display: inline-block;
+  background: var(--pb-accent);
+  color: #fff !important;
+  text-decoration: none;
+  font-weight: 700;
+  padding: 0.6rem 0.9rem;
+  border-radius: 0.65rem;
+}
+
+.hero__cta:hover {
+  background: var(--pb-accent-strong);
+}

mkdocs.yml

@@ -0,0 +1,63 @@
+site_name: PayBridge Documentation
+site_description: Production-ready integration and operations guide for PayBridge.SDK
+site_url: https://teesofttech.github.io/PayBridge/
+repo_url: https://github.com/teesofttech/PayBridge
+repo_name: teesofttech/PayBridge
+edit_uri: edit/master/docs/
+
+theme:
+  name: material
+  logo: assets/logo.svg
+  favicon: assets/logo.svg
+  language: en
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: teal
+      accent: cyan
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: teal
+      accent: cyan
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.top
+    - navigation.sections
+    - navigation.footer
+    - content.code.copy
+    - search.highlight
+    - search.suggest
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+
+extra_css:
+  - stylesheets/extra.css
+
+nav:
+  - Home: index.md
+  - Quick Start:
+      - Overview: quickstart.md
+      - Automatic Routing: automatic-gateway-routing.md
+      - Payment Idempotency: payment-idempotency.md
+  - Security:
+      - Webhook Security: webhook-security.md
+      - Webhook Replay Protection: webhook-replay-protection.md
+      - Dependency Security: dependency-security.md
+      - Credential Rotation: credential-rotation-and-history-purge.md
+  - Reliability:
+      - Integration Testing: integration-testing.md
+      - Refund Persistence: refund-persistence.md
+      - Flutterwave Refunds: flutterwave-refunds.md