From 9e59827500e01cf2307f50a9bd98f3a1e12dd9db Mon Sep 17 00:00:00 2001 From: Shashank Chandel <21042676+shashankch@users.noreply.github.com> Date: Wed, 30 Sep 2026 22:26:22 +0530 Subject: [PATCH] fix(docs): README badge destinations, Docsify portal, and GitHub Pages JaCoCo coverage - Fix CI Build badge URL to point to https://github.com/shashankch/payflow-api/actions/workflows/ci.yml (resolving 404 caused by mismatched repository owner) - Point Coverage badge to live interactive JaCoCo coverage report at https://shashankch.github.io/payflow-api/coverage/ (resolving broken fragment anchor) - Point Tests badge to Testing Strategy in docs/ARCHITECTURE.md#15-testing-strategy-rigor-concurrency--unit-verification (replacing external JUnit 5 generic URL) - Introduce zero-build Docsify documentation portal in docs-site/ (index.html, _sidebar.md, _navbar.md) publishing public docs at https://shashankch.github.io/payflow-api/ - Configure GitHub Actions CI workflow (.github/workflows/ci.yml) to stage documentation and JaCoCo coverage in public/ and deploy to GitHub Pages on push to main - Synchronize docs/adr/0030-ci-cd-quality-gates-jacoco-spotbugs.md, docs/ARCHITECTURE.md, and CHANGELOG.md with GitHub Pages deployment --- .github/workflows/ci.yml | 35 +++++++++++ CHANGELOG.md | 2 +- README.md | 8 ++- docs-site/_navbar.md | 6 ++ docs-site/_sidebar.md | 24 ++++++++ docs-site/index.html | 60 +++++++++++++++++++ docs/API_SPECIFICATION.md | 2 +- docs/ARCHITECTURE.md | 4 +- docs/CONVENTIONS.md | 3 + ...030-ci-cd-quality-gates-jacoco-spotbugs.md | 4 +- 10 files changed, 139 insertions(+), 9 deletions(-) create mode 100644 docs-site/_navbar.md create mode 100644 docs-site/_sidebar.md create mode 100644 docs-site/index.html diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 693eda8..d135e69 100644 --- 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 index 2b8d6c3..07b78cf 100644 --- 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 index 2d3a871..5f5ea28 100644 --- 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 new file mode 100644 index 0000000..9751bb2 --- /dev/null +++ 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 new file mode 100644 index 0000000..024082c --- /dev/null +++ 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 new file mode 100644 index 0000000..373658e --- /dev/null +++ b/docs-site/index.html @@ -0,0 +1,60 @@ + + + + + Payflow API — Documentation Hub + + + + + + + + + +
Loading documentation...
+ + + + + + + + + + + + + diff --git a/docs/API_SPECIFICATION.md b/docs/API_SPECIFICATION.md index 37ce3ee..95b294a 100644 --- 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 index 59e542f..f95e2b4 100644 --- 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 index a44b539..d25a9d4 100644 --- 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 index d63b1b3..a98faf3 100644 --- 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