shashankch · Sep 30, 2026 · Sep 30, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -51,3 +51,38 @@ jobs:
           path: target/spotbugsXml.xml
           retention-days: 14
           if-no-files-found: ignore
+
+      - name: Prepare Documentation and Coverage Site
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        run: |
+          mkdir -p public/coverage
+          cp README.md public/
+          cp CHANGELOG.md public/
+          cp SECURITY.md public/
+          cp -r docs public/
+          cp -r docs-site/* public/
+          cp -r target/site/jacoco/* public/coverage/
+          touch public/.nojekyll
+
+      - name: Upload Pages Artifact
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: public/
+
+  deploy-pages:
+    name: Deploy Documentation & JaCoCo to GitHub Pages
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -40,7 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Integrated `jacoco-maven-plugin:0.8.15` enforcing minimum 80% line coverage and 70% branch coverage across core business and security packages; achieved **90% line coverage** and **73% branch coverage** across 191 unit tests with 0 missed classes.
 - Created comprehensive unit test suites: `JwtAccessDeniedHandlerTest`, `JwtAuthenticationEntryPointTest`, `JwtAuthenticationFilterTest`, `SecurityUtilsTest`, and `IdempotencyCleanupServiceTest`.
 - Hardened `.github/workflows/ci.yml` executing `mvn clean verify -B` with automated artifact upload for JaCoCo coverage reports and SpotBugs analysis (14-day retention).
-- Added code coverage badge to `README.md`.
+- Added automated GitHub Pages deployment for the Docsify public documentation portal (`https://shashankch.github.io/payflow-api/`) and live interactive JaCoCo coverage reports (`https://shashankch.github.io/payflow-api/coverage/`).
 - Authored ADR-030 (*Automated CI/CD Quality Gates, JaCoCo Coverage Enforcement, and SpotBugs Static Analysis*).
 - Added `spring-modulith-events-kafka`, `spring-kafka`, `spring-kafka-test`, and Testcontainers `kafka` dependencies to `pom.xml`.
 - Marked domain event `TransferCompletedEvent` with `@Externalized` and configured programmatic dynamic routing via `EventExternalizationConfiguration` in `KafkaConfig.java`, routing to `${payflow.kafka.transfers-topic}` partitioned by `senderUpi` for strict chronological delivery per account.

diff --git a/README.md b/README.md
@@ -4,13 +4,13 @@
 
 ### Enterprise Transaction & Double-Entry Payment Ledger Engine
 
-[![CI Build](https://img.shields.io/badge/CI-Passing-brightgreen?logo=githubactions&logoColor=white&style=flat-square)](https://github.com/shashankchandel/payflow-api/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/badge/Coverage-90%25%20Line%20%7C%2073%25%20Branch-brightgreen?style=flat-square)](#-ci-cd-quality-gates-jacoco--spotbugs)
+[![CI Build](https://img.shields.io/badge/CI-Passing-brightgreen?logo=githubactions&logoColor=white&style=flat-square)](https://github.com/shashankch/payflow-api/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/Coverage-90%25%20Line%20%7C%2073%25%20Branch-brightgreen?style=flat-square)](https://shashankch.github.io/payflow-api/coverage/)
 [![Java 25](https://img.shields.io/badge/Java-25-ED8B00?logo=openjdk&logoColor=white&style=flat-square)](https://dev.java/)
 [![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.1.0-6DB33F?logo=springboot&logoColor=white&style=flat-square)](https://spring.io/projects/spring-boot)
 [![Docker](https://img.shields.io/badge/Docker-Multi--stage%20Temurin%2025-2496ED?logo=docker&logoColor=white&style=flat-square)](Dockerfile)
 [![Kubernetes](https://img.shields.io/badge/Kubernetes-HPA%20%26%20RollingUpdate-326CE5?logo=kubernetes&logoColor=white&style=flat-square)](k8s/)
-[![Tests](https://img.shields.io/badge/Tests-191%20Passing-brightgreen?logo=junit5&logoColor=white&style=flat-square)](https://junit.org/junit5/)
+[![Tests](https://img.shields.io/badge/Tests-191%20Passing-brightgreen?logo=junit5&logoColor=white&style=flat-square)](docs/ARCHITECTURE.md#15-testing-strategy-rigor-concurrency--unit-verification)
 [![Architecture](https://img.shields.io/badge/Architecture-Modular%20Monolith-6366f1?style=flat-square)](docs/ARCHITECTURE.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
 
@@ -103,6 +103,8 @@ graph TD
 
 | Document | Description |
 | :--- | :--- |
+| 🚀 **[Live Documentation Hub](https://shashankch.github.io/payflow-api/)** | Interactive Docsify portal with full-text search, dark mode, and dynamic markdown rendering |
+| 📊 **[JaCoCo Code Coverage Report](https://shashankch.github.io/payflow-api/coverage/)** | Live interactive code coverage report (90% Line, 73% Branch) generated per-build |
 | 📘 **[System Architecture](docs/ARCHITECTURE.md)** | Deep-dive concurrency models, pessimistic locking mechanics, test pyramid |
 | 🛡️ **[Security Architecture & Threat Model](docs/ARCHITECTURE.md#18-security-architecture-and-threat-model)** | Zero-Trust filter chain, STRIDE threat model, IAM policy matrix, financial concurrency controls |
 | 🔒 **[Security Policy](SECURITY.md)** | Open-source vulnerability reporting guidelines and project security posture |

diff --git a/docs-site/_navbar.md b/docs-site/_navbar.md
@@ -0,0 +1,6 @@
+- [📘 Architecture](docs/ARCHITECTURE.md)
+- [🌐 API Specs](docs/API_SPECIFICATION.md)
+- [🗓️ Roadmap](docs/ROADMAP.md)
+- [📜 ADRs](docs/adr/README.md)
+- [📊 JaCoCo Coverage](/coverage/ ':target=_blank')
+- [GitHub](https://github.com/shashankch/payflow-api)
diff --git a/docs-site/_sidebar.md b/docs-site/_sidebar.md
@@ -0,0 +1,24 @@
+- **Overview**
+  - [Home](README.md)
+  - [Changelog](CHANGELOG.md)
+  - [Security Policy](SECURITY.md)
+
+- **Architecture & Design**
+  - [System Architecture](docs/ARCHITECTURE.md)
+  - [Security Architecture](docs/ARCHITECTURE.md#18-security-architecture-and-threat-model)
+  - [Testing Strategy](docs/ARCHITECTURE.md#15-testing-strategy-rigor-concurrency--unit-verification)
+  - [Engineering Roadmap](docs/ROADMAP.md)
+
+- **API & Standards**
+  - [REST API Specification](docs/API_SPECIFICATION.md)
+  - [Engineering Conventions](docs/CONVENTIONS.md)
+
+- **Architecture Decisions (ADRs)**
+  - [ADR Index](docs/adr/README.md)
+  - [ADR-028: Multi-Stage Docker](docs/adr/0028-multi-stage-containerization-docker-compose.md)
+  - [ADR-029: Kubernetes Topology](docs/adr/0029-kubernetes-deployment-topology-hpa.md)
+  - [ADR-030: CI/CD Quality Gates](docs/adr/0030-ci-cd-quality-gates-jacoco-spotbugs.md)
+
+- **Code Quality & Telemetry**
+  - [📊 JaCoCo Coverage Report](/coverage/ ':target=_blank')
+  - [GitHub Actions CI](https://github.com/shashankch/payflow-api/actions/workflows/ci.yml)
diff --git a/docs-site/index.html b/docs-site/index.html
@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Payflow API — Documentation Hub</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Enterprise Transaction & Double-Entry Payment Ledger Engine">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css" media="(prefers-color-scheme: dark)">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css" media="(prefers-color-scheme: light)">
+  <style>
+    :root {
+      --base-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+      --theme-color: #3b82f6;
+      --sidebar-name-font-weight: 700;
+      --sidebar-name-margin: 1.5rem 0 0.5rem;
+    }
+    .sidebar-nav > ul > li > a {
+      font-weight: 600;
+    }
+  </style>
+</head>
+<body>
+  <div id="app">Loading documentation...</div>
+  <script>
+    window.$docsify = {
+      name: '₹ Payflow API',
+      repo: 'https://github.com/shashankch/payflow-api',
+      loadSidebar: true,
+      loadNavbar: true,
+      subMaxLevel: 3,
+      auto2top: true,
+      homepage: 'README.md',
+      search: {
+        maxAge: 86400000,
+        paths: 'auto',
+        placeholder: 'Search documentation...',
+        noData: 'No results found',
+        depth: 4
+      },
+      copyCode: {
+        buttonText: 'Copy',
+        errorText: 'Error',
+        successText: 'Copied'
+      }
+    };
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
+  <!-- Prism Syntax Highlighting -->
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-sql.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
+</body>
+</html>
diff --git a/docs/API_SPECIFICATION.md b/docs/API_SPECIFICATION.md
@@ -5,7 +5,7 @@
 > - **Author**: Payflow Engineering (shashakchandel@gmail.com)
 > - **Status**: Approved / Living Specification
 > - **Created Date**: 2026-08-01
-> - **Last Updated**: 2026-09-08
+> - **Last Updated**: 2026-09-30
 > - **Authoritative Location**: [API_SPECIFICATION.md](API_SPECIFICATION.md)
 > - **Related Documents**: [System Architecture](ARCHITECTURE.md) | [Security Architecture](ARCHITECTURE.md#18-security-architecture-and-threat-model) | [Architecture Decisions (ADRs)](adr/README.md) | [Phased Roadmap](ROADMAP.md) | [Engineering Conventions](CONVENTIONS.md)
 

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -5,7 +5,7 @@
 > - **Author**: Payflow Engineering (shashakchandel@gmail.com)
 > - **Status**: Approved / Living Design Document
 > - **Created Date**: 2026-08-01
-> - **Last Updated**: 2026-09-20
+> - **Last Updated**: 2026-09-30
 > - **Authoritative Location**: [ARCHITECTURE.md](ARCHITECTURE.md)
 > - **Related Documents**: [API Specification](API_SPECIFICATION.md) | [Security Policy](../SECURITY.md) | [Architecture Decisions (ADRs)](adr/README.md) | [Phased Roadmap](ROADMAP.md) | [Engineering Conventions](CONVENTIONS.md)
 
@@ -660,7 +660,7 @@ In distributed Kubernetes environments, terminating pods requires coordinated dr
   - **Line Coverage**: Minimum 80% (Achieved: **90%** across 191 tests).
   - **Branch Coverage**: Minimum 70% (Achieved: **73%** across 191 tests).
   - Pure DTOs, configuration classes, entities, and generated MapStruct classes are excluded from coverage calculations.
-- **GitHub Actions Workflow Hardening**: `.github/workflows/ci.yml` executes `mvn clean verify -B`, failing fast on formatting, checkstyle, test failures, SpotBugs warnings, or coverage violations, while uploading JaCoCo and SpotBugs report artifacts for 14-day retention.
+- **GitHub Actions Workflow Hardening**: `.github/workflows/ci.yml` executes `mvn clean verify -B`, failing fast on formatting, checkstyle, test failures, SpotBugs warnings, or coverage violations, while uploading JaCoCo and SpotBugs report artifacts for 14-day retention and deploying the Docsify documentation portal (`https://shashankch.github.io/payflow-api/`) with live interactive JaCoCo coverage reports (`https://shashankch.github.io/payflow-api/coverage/`) to GitHub Pages.
 
 ---
 

diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md
@@ -60,6 +60,9 @@ This document outlines the coding standards, repository conventions, Git workflo
 - **Test Method Naming**: Use descriptive names reflecting intent:
   - `should[ExpectedBehavior]_when[StateUnderTest]()`
   - Example: `shouldRejectTransfer_whenSenderHasInsufficientBalance()`
+- **Quality Gates & Static Analysis**:
+  - `spotbugs-maven-plugin` enforces zero static bytecode bugs during `mvn verify`.
+  - `jacoco-maven-plugin` enforces strict bundle-level code coverage thresholds (minimum 80% line, 70% branch coverage across domain, service, and security packages) with automated GitHub Pages live reporting.
 
 ---
 

diff --git a/docs/adr/0030-ci-cd-quality-gates-jacoco-spotbugs.md b/docs/adr/0030-ci-cd-quality-gates-jacoco-spotbugs.md
@@ -52,8 +52,8 @@ We adopted **Option C**. The quality enforcement system consists of:
 
 3. **Hardened GitHub Actions CI Pipeline**:
    - Updated `.github/workflows/ci.yml` to run `mvn clean verify -B`.
-   - Added automated artifact upload for `target/site/jacoco/` and `target/spotbugsXml.xml` with 14-day retention.
-   - Added code coverage status badge to `README.md`.
+   - Added automated GitHub Pages deployment for Docsify public documentation portal (`https://shashankch.github.io/payflow-api/`) and live interactive JaCoCo coverage reports at `https://shashankch.github.io/payflow-api/coverage/`.
+   - Added code coverage status badge to `README.md` linking directly to the live GitHub Pages report.
 
 ## Consequences