FINERACT-2757: modular design developer documentation

[mansi75]

Description

This PR adds developer documentation and supporting architecture analysis for cross-feature boundary violations in Apache Fineract as part of FINERACT-2757.

The documentation provides a measured view of dependencies between Fineract features and packages and explains how those dependencies can be progressively reduced as Fineract moves towards stronger module boundaries and an event-driven architecture.

Instead of relying only on package naming conventions or manual analysis, the architecture metrics are generated from compiled bytecode through the Gradle build. The analysis produces both a package-level view, which acts as the ground truth without making feature-grouping assumptions, and a feature-level view that makes the dependency structure easier to understand and document.

The documentation also distinguishes between different forms of coupling — compile-time, database, infrastructure, and runtime/transactional coupling — so that removing a Java dependency is not incorrectly treated as removing the underlying domain or data relationship.

Changes in this PR:

• Add fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc containing the cross-feature boundary violation analysis and developer guidance.
• Add a reproducible architecture metrics pipeline based on io.github.usekylis.java-architecture-metrics.
• Run the architecture analysis as a single aggregate scan across Java modules so cross-module dependencies are retained.
• Generate both package-level and feature-level architecture reports.
• Add a feature classifier for producing the higher-level feature dependency view.
• Add tools/archmetrics_to_vega.py for transforming generated architecture metrics into documentation data and Vega-Lite visualisations.
• Add Vega-Lite visualisations for:
  • Abstractness vs Instability.
  • Distance from the Main Sequence.
  • Cross-feature dependency matrix.
• Add fineract-doc/src/docs/en/chapters/architecture/generated-package-overview.adoc, providing a generated section for each measured package and a consistent location for future architectural analysis.
• Add worked case studies covering different levels of cross-feature coupling and possible remediation approaches.
• Add guidance for deciding which feature dependencies are appropriate candidates for decoupling.
• Add documentation describing how cleaned module boundaries can be protected from regression.

The architecture metrics, generated documentation, and diagram data can be regenerated using:

./gradlew architectureMetricsReport

This PR primarily adds developer documentation and architecture-analysis tooling. There are no REST API, database schema, or externally visible behavioural changes.

Related JIRA: https://issues.apache.org/jira/browse/FINERACT-2757

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

• Write the commit message as per our guidelines
• Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
• Create/update unit or integration tests for verifying the changes made. — N/A: this PR adds developer documentation and architecture-analysis/build tooling rather than application behaviour. The generated architecture reports and documentation are produced through the Gradle architecture metrics task.
• Follow our coding conventions.
• Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes — N/A: no API changes.
• This PR must not be a "code dump". Large changes can be made in a branch, with assistance. Ask for help on the developer mailing list.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

Your assigned reviewer(s) will follow our guidelines for code reviews.

[Copilot]

Pull request overview

This PR adds a reproducible architecture-metrics pipeline (generated from compiled bytecode via Gradle) and accompanying developer documentation/visualisations to analyze and explain cross-feature boundary violations as part of FINERACT-2757.

Changes:

• Introduces Gradle-based architecture metrics reporting (package-level and feature-level), plus tasks to regenerate documentation artifacts.
• Adds a Python transformer to turn the generated metrics JSON into Vega-Lite specs and an AsciiDoc “skeleton” reference.
• Adds extensive architecture documentation and commits the generated Vega-Lite diagram specifications used by the docs.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/archmetrics_to_vega.py	New CLI tool to transform architecture metrics JSON into Vega-Lite specs and generate AsciiDoc skeleton sections.
fineract-doc/src/docs/en/diagrams/main-sequence.vl.json	Adds a generated Vega-Lite spec for abstractness vs instability visualisation.
fineract-doc/src/docs/en/diagrams/distance-ranking.vl.json	Adds a generated Vega-Lite spec for distance ranking visualisation.
fineract-doc/src/docs/en/diagrams/cross-feature-matrix.vl.json	Adds a generated Vega-Lite spec for the cross-feature dependency matrix.
fineract-doc/src/docs/en/chapters/architecture/index.adoc	Wires the new cross-feature boundary violations chapter into the architecture docs index.
fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc	Adds the new detailed chapter describing CFVs, measurements, case studies, and regeneration guidance.
build.gradle	Adds and configures the java-architecture-metrics plugin plus aggregate/reporting/regen tasks to produce reports and docs artifacts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[vidakovic]

LGTM

[meonkeys]

Why do all the text lines in fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc wrap at ~85 characters? We use :hardbreaks: so each newline in the source forces a "carriage return", breaking automatic right margin during rendering for everything in the "Cross-Feature Boundary Violations" chapter.

Please take a look at fineract-doc/src/docs/en/chapters/architecture/batch-jobs.adoc vs. fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc... we want all the asciidoc to use long lines and to let Asciidoctor handle line wrapping in PDF output and the browser to handle line wrapping in HTML output. Or we need to stop using :hardbreaks:, but I'm guessing that's more work.

:hardbreaks: is configured in fineract-doc/src/docs/en/config.adoc and documented in Hard Line Breaks.

See FINERACT-2795

[mansi75]

Description

This PR adds developer documentation and supporting architecture analysis for cross-feature boundary violations in Apache Fineract as part of FINERACT-2757.

The documentation provides a measured view of dependencies between Fineract features and packages and explains how those dependencies can be progressively reduced as Fineract moves towards stronger module boundaries and an event-driven architecture.

Instead of relying only on package naming conventions or manual analysis, the architecture metrics are generated from compiled bytecode through the Gradle build. The analysis produces both a package-level view, which acts as the ground truth without making feature-grouping assumptions, and a feature-level view that makes the dependency structure easier to understand and document.

The documentation also distinguishes between different forms of coupling — compile-time, database, infrastructure, and runtime/transactional coupling — so that removing a Java dependency is not incorrectly treated as removing the underlying domain or data relationship.

Changes in this PR:

• Add fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc containing the cross-feature boundary violation analysis and developer guidance.
• Add a reproducible architecture metrics pipeline based on io.github.usekylis.java-architecture-metrics.
• Run the architecture analysis as a single aggregate scan across Java modules so cross-module dependencies are retained.
• Generate both package-level and feature-level architecture reports.
• Add a feature classifier for producing the higher-level feature dependency view.
• Add tools/archmetrics_to_vega.py for transforming generated architecture metrics into documentation data and Vega-Lite visualisations.
• Add Vega-Lite visualisations for:
  • Abstractness vs Instability.
  • Distance from the Main Sequence.
  • Cross-feature dependency matrix.
• Add fineract-doc/src/docs/en/chapters/architecture/generated-package-overview.adoc, providing a generated section for each measured package and a consistent location for future architectural analysis.
• Add worked case studies covering different levels of cross-feature coupling and possible remediation approaches.
• Add guidance for deciding which feature dependencies are appropriate candidates for decoupling.
• Add documentation describing how cleaned module boundaries can be protected from regression.

The architecture metrics, generated documentation, and diagram data can be regenerated using:

./gradlew architectureMetricsReport

This PR primarily adds developer documentation and architecture-analysis tooling. There are no REST API, database schema, or externally visible behavioural changes.

Related JIRA: https://issues.apache.org/jira/browse/FINERACT-2757

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

• Write the commit message as per our guidelines
• Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
• Create/update unit or integration tests for verifying the changes made. — N/A: this PR adds developer documentation and architecture-analysis/build tooling rather than application behaviour. The generated architecture reports and documentation are produced through the Gradle architecture metrics task.
• Follow our coding conventions.
• Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes — N/A: no API changes.
• This PR must not be a "code dump". Large changes can be made in a branch, with assistance. Ask for help on the developer mailing list.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

Your assigned reviewer(s) will follow our guidelines for code reviews.

[Copilot]

Pull request overview

This PR adds a reproducible architecture-metrics pipeline (generated from compiled bytecode via Gradle) and accompanying developer documentation/visualisations to analyze and explain cross-feature boundary violations as part of FINERACT-2757.

Changes:

• Introduces Gradle-based architecture metrics reporting (package-level and feature-level), plus tasks to regenerate documentation artifacts.
• Adds a Python transformer to turn the generated metrics JSON into Vega-Lite specs and an AsciiDoc “skeleton” reference.
• Adds extensive architecture documentation and commits the generated Vega-Lite diagram specifications used by the docs.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/archmetrics_to_vega.py	New CLI tool to transform architecture metrics JSON into Vega-Lite specs and generate AsciiDoc skeleton sections.
fineract-doc/src/docs/en/diagrams/main-sequence.vl.json	Adds a generated Vega-Lite spec for abstractness vs instability visualisation.
fineract-doc/src/docs/en/diagrams/distance-ranking.vl.json	Adds a generated Vega-Lite spec for distance ranking visualisation.
fineract-doc/src/docs/en/diagrams/cross-feature-matrix.vl.json	Adds a generated Vega-Lite spec for the cross-feature dependency matrix.
fineract-doc/src/docs/en/chapters/architecture/index.adoc	Wires the new cross-feature boundary violations chapter into the architecture docs index.
fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc	Adds the new detailed chapter describing CFVs, measurements, case studies, and regeneration guidance.
build.gradle	Adds and configures the java-architecture-metrics plugin plus aggregate/reporting/regen tasks to produce reports and docs artifacts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[vidakovic]

LGTM

[meonkeys]

Why do all the text lines in fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc wrap at ~85 characters? We use :hardbreaks: so each newline in the source forces a "carriage return", breaking automatic right margin during rendering for everything in the "Cross-Feature Boundary Violations" chapter.

Please take a look at fineract-doc/src/docs/en/chapters/architecture/batch-jobs.adoc vs. fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc... we want all the asciidoc to use long lines and to let Asciidoctor handle line wrapping in PDF output and the browser to handle line wrapping in HTML output. Or we need to stop using :hardbreaks:, but I'm guessing that's more work.

:hardbreaks: is configured in fineract-doc/src/docs/en/config.adoc and documented in Hard Line Breaks.

See FINERACT-2795

[mansi75]

Description

This PR adds developer documentation and supporting architecture analysis for cross-feature boundary violations in Apache Fineract as part of FINERACT-2757.

The documentation provides a measured view of dependencies between Fineract features and packages and explains how those dependencies can be progressively reduced as Fineract moves towards stronger module boundaries and an event-driven architecture.

Instead of relying only on package naming conventions or manual analysis, the architecture metrics are generated from compiled bytecode through the Gradle build. The analysis produces both a package-level view, which acts as the ground truth without making feature-grouping assumptions, and a feature-level view that makes the dependency structure easier to understand and document.

The documentation also distinguishes between different forms of coupling — compile-time, database, infrastructure, and runtime/transactional coupling — so that removing a Java dependency is not incorrectly treated as removing the underlying domain or data relationship.

Changes in this PR:

• Add fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc containing the cross-feature boundary violation analysis and developer guidance.
• Add a reproducible architecture metrics pipeline based on io.github.usekylis.java-architecture-metrics.
• Run the architecture analysis as a single aggregate scan across Java modules so cross-module dependencies are retained.
• Generate both package-level and feature-level architecture reports.
• Add a feature classifier for producing the higher-level feature dependency view.
• Add tools/archmetrics_to_vega.py for transforming generated architecture metrics into documentation data and Vega-Lite visualisations.
• Add Vega-Lite visualisations for:
  • Abstractness vs Instability.
  • Distance from the Main Sequence.
  • Cross-feature dependency matrix.
• Add fineract-doc/src/docs/en/chapters/architecture/generated-package-overview.adoc, providing a generated section for each measured package and a consistent location for future architectural analysis.
• Add worked case studies covering different levels of cross-feature coupling and possible remediation approaches.
• Add guidance for deciding which feature dependencies are appropriate candidates for decoupling.
• Add documentation describing how cleaned module boundaries can be protected from regression.

The architecture metrics, generated documentation, and diagram data can be regenerated using:

./gradlew architectureMetricsReport

This PR primarily adds developer documentation and architecture-analysis tooling. There are no REST API, database schema, or externally visible behavioural changes.

Related JIRA: https://issues.apache.org/jira/browse/FINERACT-2757

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

• Write the commit message as per our guidelines
• Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
• Create/update unit or integration tests for verifying the changes made. — N/A: this PR adds developer documentation and architecture-analysis/build tooling rather than application behaviour. The generated architecture reports and documentation are produced through the Gradle architecture metrics task.
• Follow our coding conventions.
• Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes — N/A: no API changes.
• This PR must not be a "code dump". Large changes can be made in a branch, with assistance. Ask for help on the developer mailing list.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

Your assigned reviewer(s) will follow our guidelines for code reviews.

[Copilot]

Pull request overview

This PR adds a reproducible architecture-metrics pipeline (generated from compiled bytecode via Gradle) and accompanying developer documentation/visualisations to analyze and explain cross-feature boundary violations as part of FINERACT-2757.

Changes:

• Introduces Gradle-based architecture metrics reporting (package-level and feature-level), plus tasks to regenerate documentation artifacts.
• Adds a Python transformer to turn the generated metrics JSON into Vega-Lite specs and an AsciiDoc “skeleton” reference.
• Adds extensive architecture documentation and commits the generated Vega-Lite diagram specifications used by the docs.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/archmetrics_to_vega.py	New CLI tool to transform architecture metrics JSON into Vega-Lite specs and generate AsciiDoc skeleton sections.
fineract-doc/src/docs/en/diagrams/main-sequence.vl.json	Adds a generated Vega-Lite spec for abstractness vs instability visualisation.
fineract-doc/src/docs/en/diagrams/distance-ranking.vl.json	Adds a generated Vega-Lite spec for distance ranking visualisation.
fineract-doc/src/docs/en/diagrams/cross-feature-matrix.vl.json	Adds a generated Vega-Lite spec for the cross-feature dependency matrix.
fineract-doc/src/docs/en/chapters/architecture/index.adoc	Wires the new cross-feature boundary violations chapter into the architecture docs index.
fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc	Adds the new detailed chapter describing CFVs, measurements, case studies, and regeneration guidance.
build.gradle	Adds and configures the java-architecture-metrics plugin plus aggregate/reporting/regen tasks to produce reports and docs artifacts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[vidakovic]

LGTM

[meonkeys]

Why do all the text lines in fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc wrap at ~85 characters? We use :hardbreaks: so each newline in the source forces a "carriage return", breaking automatic right margin during rendering for everything in the "Cross-Feature Boundary Violations" chapter.

Please take a look at fineract-doc/src/docs/en/chapters/architecture/batch-jobs.adoc vs. fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc... we want all the asciidoc to use long lines and to let Asciidoctor handle line wrapping in PDF output and the browser to handle line wrapping in HTML output. Or we need to stop using :hardbreaks:, but I'm guessing that's more work.

:hardbreaks: is configured in fineract-doc/src/docs/en/config.adoc and documented in Hard Line Breaks.

See FINERACT-2795

[mansi75]

Description

This PR adds developer documentation and supporting architecture analysis for cross-feature boundary violations in Apache Fineract as part of FINERACT-2757.

The documentation provides a measured view of dependencies between Fineract features and packages and explains how those dependencies can be progressively reduced as Fineract moves towards stronger module boundaries and an event-driven architecture.

Instead of relying only on package naming conventions or manual analysis, the architecture metrics are generated from compiled bytecode through the Gradle build. The analysis produces both a package-level view, which acts as the ground truth without making feature-grouping assumptions, and a feature-level view that makes the dependency structure easier to understand and document.

The documentation also distinguishes between different forms of coupling — compile-time, database, infrastructure, and runtime/transactional coupling — so that removing a Java dependency is not incorrectly treated as removing the underlying domain or data relationship.

Changes in this PR:

• Add fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc containing the cross-feature boundary violation analysis and developer guidance.
• Add a reproducible architecture metrics pipeline based on io.github.usekylis.java-architecture-metrics.
• Run the architecture analysis as a single aggregate scan across Java modules so cross-module dependencies are retained.
• Generate both package-level and feature-level architecture reports.
• Add a feature classifier for producing the higher-level feature dependency view.
• Add tools/archmetrics_to_vega.py for transforming generated architecture metrics into documentation data and Vega-Lite visualisations.
• Add Vega-Lite visualisations for:
  • Abstractness vs Instability.
  • Distance from the Main Sequence.
  • Cross-feature dependency matrix.
• Add fineract-doc/src/docs/en/chapters/architecture/generated-package-overview.adoc, providing a generated section for each measured package and a consistent location for future architectural analysis.
• Add worked case studies covering different levels of cross-feature coupling and possible remediation approaches.
• Add guidance for deciding which feature dependencies are appropriate candidates for decoupling.
• Add documentation describing how cleaned module boundaries can be protected from regression.

The architecture metrics, generated documentation, and diagram data can be regenerated using:

./gradlew architectureMetricsReport

This PR primarily adds developer documentation and architecture-analysis tooling. There are no REST API, database schema, or externally visible behavioural changes.

Related JIRA: https://issues.apache.org/jira/browse/FINERACT-2757

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

• Write the commit message as per our guidelines
• Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
• Create/update unit or integration tests for verifying the changes made. — N/A: this PR adds developer documentation and architecture-analysis/build tooling rather than application behaviour. The generated architecture reports and documentation are produced through the Gradle architecture metrics task.
• Follow our coding conventions.
• Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes — N/A: no API changes.
• This PR must not be a "code dump". Large changes can be made in a branch, with assistance. Ask for help on the developer mailing list.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

Your assigned reviewer(s) will follow our guidelines for code reviews.

[Copilot]

Pull request overview

This PR adds a reproducible architecture-metrics pipeline (generated from compiled bytecode via Gradle) and accompanying developer documentation/visualisations to analyze and explain cross-feature boundary violations as part of FINERACT-2757.

Changes:

• Introduces Gradle-based architecture metrics reporting (package-level and feature-level), plus tasks to regenerate documentation artifacts.
• Adds a Python transformer to turn the generated metrics JSON into Vega-Lite specs and an AsciiDoc “skeleton” reference.
• Adds extensive architecture documentation and commits the generated Vega-Lite diagram specifications used by the docs.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/archmetrics_to_vega.py	New CLI tool to transform architecture metrics JSON into Vega-Lite specs and generate AsciiDoc skeleton sections.
fineract-doc/src/docs/en/diagrams/main-sequence.vl.json	Adds a generated Vega-Lite spec for abstractness vs instability visualisation.
fineract-doc/src/docs/en/diagrams/distance-ranking.vl.json	Adds a generated Vega-Lite spec for distance ranking visualisation.
fineract-doc/src/docs/en/diagrams/cross-feature-matrix.vl.json	Adds a generated Vega-Lite spec for the cross-feature dependency matrix.
fineract-doc/src/docs/en/chapters/architecture/index.adoc	Wires the new cross-feature boundary violations chapter into the architecture docs index.
fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc	Adds the new detailed chapter describing CFVs, measurements, case studies, and regeneration guidance.
build.gradle	Adds and configures the java-architecture-metrics plugin plus aggregate/reporting/regen tasks to produce reports and docs artifacts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[vidakovic]

LGTM

[meonkeys]

Why do all the text lines in fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc wrap at ~85 characters? We use :hardbreaks: so each newline in the source forces a "carriage return", breaking automatic right margin during rendering for everything in the "Cross-Feature Boundary Violations" chapter.

Please take a look at fineract-doc/src/docs/en/chapters/architecture/batch-jobs.adoc vs. fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc... we want all the asciidoc to use long lines and to let Asciidoctor handle line wrapping in PDF output and the browser to handle line wrapping in HTML output. Or we need to stop using :hardbreaks:, but I'm guessing that's more work.

:hardbreaks: is configured in fineract-doc/src/docs/en/config.adoc and documented in Hard Line Breaks.

See FINERACT-2795

[mansi75]

Description

This PR adds developer documentation and supporting architecture analysis for cross-feature boundary violations in Apache Fineract as part of FINERACT-2757.

The documentation provides a measured view of dependencies between Fineract features and packages and explains how those dependencies can be progressively reduced as Fineract moves towards stronger module boundaries and an event-driven architecture.

Instead of relying only on package naming conventions or manual analysis, the architecture metrics are generated from compiled bytecode through the Gradle build. The analysis produces both a package-level view, which acts as the ground truth without making feature-grouping assumptions, and a feature-level view that makes the dependency structure easier to understand and document.

The documentation also distinguishes between different forms of coupling — compile-time, database, infrastructure, and runtime/transactional coupling — so that removing a Java dependency is not incorrectly treated as removing the underlying domain or data relationship.

Changes in this PR:

• Add fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc containing the cross-feature boundary violation analysis and developer guidance.
• Add a reproducible architecture metrics pipeline based on io.github.usekylis.java-architecture-metrics.
• Run the architecture analysis as a single aggregate scan across Java modules so cross-module dependencies are retained.
• Generate both package-level and feature-level architecture reports.
• Add a feature classifier for producing the higher-level feature dependency view.
• Add tools/archmetrics_to_vega.py for transforming generated architecture metrics into documentation data and Vega-Lite visualisations.
• Add Vega-Lite visualisations for:
  • Abstractness vs Instability.
  • Distance from the Main Sequence.
  • Cross-feature dependency matrix.
• Add fineract-doc/src/docs/en/chapters/architecture/generated-package-overview.adoc, providing a generated section for each measured package and a consistent location for future architectural analysis.
• Add worked case studies covering different levels of cross-feature coupling and possible remediation approaches.
• Add guidance for deciding which feature dependencies are appropriate candidates for decoupling.
• Add documentation describing how cleaned module boundaries can be protected from regression.

The architecture metrics, generated documentation, and diagram data can be regenerated using:

./gradlew architectureMetricsReport

This PR primarily adds developer documentation and architecture-analysis tooling. There are no REST API, database schema, or externally visible behavioural changes.

Related JIRA: https://issues.apache.org/jira/browse/FINERACT-2757

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

• Write the commit message as per our guidelines
• Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
• Create/update unit or integration tests for verifying the changes made. — N/A: this PR adds developer documentation and architecture-analysis/build tooling rather than application behaviour. The generated architecture reports and documentation are produced through the Gradle architecture metrics task.
• Follow our coding conventions.
• Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes — N/A: no API changes.
• This PR must not be a "code dump". Large changes can be made in a branch, with assistance. Ask for help on the developer mailing list.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

Your assigned reviewer(s) will follow our guidelines for code reviews.

[Copilot]

Pull request overview

This PR adds a reproducible architecture-metrics pipeline (generated from compiled bytecode via Gradle) and accompanying developer documentation/visualisations to analyze and explain cross-feature boundary violations as part of FINERACT-2757.

Changes:

• Introduces Gradle-based architecture metrics reporting (package-level and feature-level), plus tasks to regenerate documentation artifacts.
• Adds a Python transformer to turn the generated metrics JSON into Vega-Lite specs and an AsciiDoc “skeleton” reference.
• Adds extensive architecture documentation and commits the generated Vega-Lite diagram specifications used by the docs.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/archmetrics_to_vega.py	New CLI tool to transform architecture metrics JSON into Vega-Lite specs and generate AsciiDoc skeleton sections.
fineract-doc/src/docs/en/diagrams/main-sequence.vl.json	Adds a generated Vega-Lite spec for abstractness vs instability visualisation.
fineract-doc/src/docs/en/diagrams/distance-ranking.vl.json	Adds a generated Vega-Lite spec for distance ranking visualisation.
fineract-doc/src/docs/en/diagrams/cross-feature-matrix.vl.json	Adds a generated Vega-Lite spec for the cross-feature dependency matrix.
fineract-doc/src/docs/en/chapters/architecture/index.adoc	Wires the new cross-feature boundary violations chapter into the architecture docs index.
fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc	Adds the new detailed chapter describing CFVs, measurements, case studies, and regeneration guidance.
build.gradle	Adds and configures the java-architecture-metrics plugin plus aggregate/reporting/regen tasks to produce reports and docs artifacts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[vidakovic]

LGTM

[meonkeys]

Why do all the text lines in fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc wrap at ~85 characters? We use :hardbreaks: so each newline in the source forces a "carriage return", breaking automatic right margin during rendering for everything in the "Cross-Feature Boundary Violations" chapter.

Please take a look at fineract-doc/src/docs/en/chapters/architecture/batch-jobs.adoc vs. fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc... we want all the asciidoc to use long lines and to let Asciidoctor handle line wrapping in PDF output and the browser to handle line wrapping in HTML output. Or we need to stop using :hardbreaks:, but I'm guessing that's more work.

:hardbreaks: is configured in fineract-doc/src/docs/en/config.adoc and documented in Hard Line Breaks.

See FINERACT-2795

[mansi75]

Description

This PR adds developer documentation and supporting architecture analysis for cross-feature boundary violations in Apache Fineract as part of FINERACT-2757.

The documentation provides a measured view of dependencies between Fineract features and packages and explains how those dependencies can be progressively reduced as Fineract moves towards stronger module boundaries and an event-driven architecture.

Instead of relying only on package naming conventions or manual analysis, the architecture metrics are generated from compiled bytecode through the Gradle build. The analysis produces both a package-level view, which acts as the ground truth without making feature-grouping assumptions, and a feature-level view that makes the dependency structure easier to understand and document.

The documentation also distinguishes between different forms of coupling — compile-time, database, infrastructure, and runtime/transactional coupling — so that removing a Java dependency is not incorrectly treated as removing the underlying domain or data relationship.

Changes in this PR:

• Add fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc containing the cross-feature boundary violation analysis and developer guidance.
• Add a reproducible architecture metrics pipeline based on io.github.usekylis.java-architecture-metrics.
• Run the architecture analysis as a single aggregate scan across Java modules so cross-module dependencies are retained.
• Generate both package-level and feature-level architecture reports.
• Add a feature classifier for producing the higher-level feature dependency view.
• Add tools/archmetrics_to_vega.py for transforming generated architecture metrics into documentation data and Vega-Lite visualisations.
• Add Vega-Lite visualisations for:
  • Abstractness vs Instability.
  • Distance from the Main Sequence.
  • Cross-feature dependency matrix.
• Add fineract-doc/src/docs/en/chapters/architecture/generated-package-overview.adoc, providing a generated section for each measured package and a consistent location for future architectural analysis.
• Add worked case studies covering different levels of cross-feature coupling and possible remediation approaches.
• Add guidance for deciding which feature dependencies are appropriate candidates for decoupling.
• Add documentation describing how cleaned module boundaries can be protected from regression.

The architecture metrics, generated documentation, and diagram data can be regenerated using:

./gradlew architectureMetricsReport

This PR primarily adds developer documentation and architecture-analysis tooling. There are no REST API, database schema, or externally visible behavioural changes.

Related JIRA: https://issues.apache.org/jira/browse/FINERACT-2757

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

• Write the commit message as per our guidelines
• Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
• Create/update unit or integration tests for verifying the changes made. — N/A: this PR adds developer documentation and architecture-analysis/build tooling rather than application behaviour. The generated architecture reports and documentation are produced through the Gradle architecture metrics task.
• Follow our coding conventions.
• Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes — N/A: no API changes.
• This PR must not be a "code dump". Large changes can be made in a branch, with assistance. Ask for help on the developer mailing list.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

Your assigned reviewer(s) will follow our guidelines for code reviews.

[Copilot]

Pull request overview

This PR adds a reproducible architecture-metrics pipeline (generated from compiled bytecode via Gradle) and accompanying developer documentation/visualisations to analyze and explain cross-feature boundary violations as part of FINERACT-2757.

Changes:

• Introduces Gradle-based architecture metrics reporting (package-level and feature-level), plus tasks to regenerate documentation artifacts.
• Adds a Python transformer to turn the generated metrics JSON into Vega-Lite specs and an AsciiDoc “skeleton” reference.
• Adds extensive architecture documentation and commits the generated Vega-Lite diagram specifications used by the docs.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/archmetrics_to_vega.py	New CLI tool to transform architecture metrics JSON into Vega-Lite specs and generate AsciiDoc skeleton sections.
fineract-doc/src/docs/en/diagrams/main-sequence.vl.json	Adds a generated Vega-Lite spec for abstractness vs instability visualisation.
fineract-doc/src/docs/en/diagrams/distance-ranking.vl.json	Adds a generated Vega-Lite spec for distance ranking visualisation.
fineract-doc/src/docs/en/diagrams/cross-feature-matrix.vl.json	Adds a generated Vega-Lite spec for the cross-feature dependency matrix.
fineract-doc/src/docs/en/chapters/architecture/index.adoc	Wires the new cross-feature boundary violations chapter into the architecture docs index.
fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc	Adds the new detailed chapter describing CFVs, measurements, case studies, and regeneration guidance.
build.gradle	Adds and configures the java-architecture-metrics plugin plus aggregate/reporting/regen tasks to produce reports and docs artifacts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[vidakovic]

LGTM

[meonkeys]

Why do all the text lines in fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc wrap at ~85 characters? We use :hardbreaks: so each newline in the source forces a "carriage return", breaking automatic right margin during rendering for everything in the "Cross-Feature Boundary Violations" chapter.

Please take a look at fineract-doc/src/docs/en/chapters/architecture/batch-jobs.adoc vs. fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc... we want all the asciidoc to use long lines and to let Asciidoctor handle line wrapping in PDF output and the browser to handle line wrapping in HTML output. Or we need to stop using :hardbreaks:, but I'm guessing that's more work.

:hardbreaks: is configured in fineract-doc/src/docs/en/config.adoc and documented in Hard Line Breaks.

See FINERACT-2795

[mansi75]

Description

This PR adds developer documentation and supporting architecture analysis for cross-feature boundary violations in Apache Fineract as part of FINERACT-2757.

The documentation provides a measured view of dependencies between Fineract features and packages and explains how those dependencies can be progressively reduced as Fineract moves towards stronger module boundaries and an event-driven architecture.

Instead of relying only on package naming conventions or manual analysis, the architecture metrics are generated from compiled bytecode through the Gradle build. The analysis produces both a package-level view, which acts as the ground truth without making feature-grouping assumptions, and a feature-level view that makes the dependency structure easier to understand and document.

The documentation also distinguishes between different forms of coupling — compile-time, database, infrastructure, and runtime/transactional coupling — so that removing a Java dependency is not incorrectly treated as removing the underlying domain or data relationship.

Changes in this PR:

• Add fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc containing the cross-feature boundary violation analysis and developer guidance.
• Add a reproducible architecture metrics pipeline based on io.github.usekylis.java-architecture-metrics.
• Run the architecture analysis as a single aggregate scan across Java modules so cross-module dependencies are retained.
• Generate both package-level and feature-level architecture reports.
• Add a feature classifier for producing the higher-level feature dependency view.
• Add tools/archmetrics_to_vega.py for transforming generated architecture metrics into documentation data and Vega-Lite visualisations.
• Add Vega-Lite visualisations for:
  • Abstractness vs Instability.
  • Distance from the Main Sequence.
  • Cross-feature dependency matrix.
• Add fineract-doc/src/docs/en/chapters/architecture/generated-package-overview.adoc, providing a generated section for each measured package and a consistent location for future architectural analysis.
• Add worked case studies covering different levels of cross-feature coupling and possible remediation approaches.
• Add guidance for deciding which feature dependencies are appropriate candidates for decoupling.
• Add documentation describing how cleaned module boundaries can be protected from regression.

The architecture metrics, generated documentation, and diagram data can be regenerated using:

./gradlew architectureMetricsReport

This PR primarily adds developer documentation and architecture-analysis tooling. There are no REST API, database schema, or externally visible behavioural changes.

Related JIRA: https://issues.apache.org/jira/browse/FINERACT-2757

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

• Write the commit message as per our guidelines
• Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
• Create/update unit or integration tests for verifying the changes made. — N/A: this PR adds developer documentation and architecture-analysis/build tooling rather than application behaviour. The generated architecture reports and documentation are produced through the Gradle architecture metrics task.
• Follow our coding conventions.
• Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes — N/A: no API changes.
• This PR must not be a "code dump". Large changes can be made in a branch, with assistance. Ask for help on the developer mailing list.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

Your assigned reviewer(s) will follow our guidelines for code reviews.

[Copilot]

Pull request overview

This PR adds a reproducible architecture-metrics pipeline (generated from compiled bytecode via Gradle) and accompanying developer documentation/visualisations to analyze and explain cross-feature boundary violations as part of FINERACT-2757.

Changes:

• Introduces Gradle-based architecture metrics reporting (package-level and feature-level), plus tasks to regenerate documentation artifacts.
• Adds a Python transformer to turn the generated metrics JSON into Vega-Lite specs and an AsciiDoc “skeleton” reference.
• Adds extensive architecture documentation and commits the generated Vega-Lite diagram specifications used by the docs.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/archmetrics_to_vega.py	New CLI tool to transform architecture metrics JSON into Vega-Lite specs and generate AsciiDoc skeleton sections.
fineract-doc/src/docs/en/diagrams/main-sequence.vl.json	Adds a generated Vega-Lite spec for abstractness vs instability visualisation.
fineract-doc/src/docs/en/diagrams/distance-ranking.vl.json	Adds a generated Vega-Lite spec for distance ranking visualisation.
fineract-doc/src/docs/en/diagrams/cross-feature-matrix.vl.json	Adds a generated Vega-Lite spec for the cross-feature dependency matrix.
fineract-doc/src/docs/en/chapters/architecture/index.adoc	Wires the new cross-feature boundary violations chapter into the architecture docs index.
fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc	Adds the new detailed chapter describing CFVs, measurements, case studies, and regeneration guidance.
build.gradle	Adds and configures the java-architecture-metrics plugin plus aggregate/reporting/regen tasks to produce reports and docs artifacts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[vidakovic]

LGTM

[meonkeys]

Why do all the text lines in fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc wrap at ~85 characters? We use :hardbreaks: so each newline in the source forces a "carriage return", breaking automatic right margin during rendering for everything in the "Cross-Feature Boundary Violations" chapter.

Please take a look at fineract-doc/src/docs/en/chapters/architecture/batch-jobs.adoc vs. fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc... we want all the asciidoc to use long lines and to let Asciidoctor handle line wrapping in PDF output and the browser to handle line wrapping in HTML output. Or we need to stop using :hardbreaks:, but I'm guessing that's more work.

:hardbreaks: is configured in fineract-doc/src/docs/en/config.adoc and documented in Hard Line Breaks.

See FINERACT-2795

[mansi75]

Description

This PR adds developer documentation and supporting architecture analysis for cross-feature boundary violations in Apache Fineract as part of FINERACT-2757.

The documentation provides a measured view of dependencies between Fineract features and packages and explains how those dependencies can be progressively reduced as Fineract moves towards stronger module boundaries and an event-driven architecture.

Instead of relying only on package naming conventions or manual analysis, the architecture metrics are generated from compiled bytecode through the Gradle build. The analysis produces both a package-level view, which acts as the ground truth without making feature-grouping assumptions, and a feature-level view that makes the dependency structure easier to understand and document.

The documentation also distinguishes between different forms of coupling — compile-time, database, infrastructure, and runtime/transactional coupling — so that removing a Java dependency is not incorrectly treated as removing the underlying domain or data relationship.

Changes in this PR:

• Add fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc containing the cross-feature boundary violation analysis and developer guidance.
• Add a reproducible architecture metrics pipeline based on io.github.usekylis.java-architecture-metrics.
• Run the architecture analysis as a single aggregate scan across Java modules so cross-module dependencies are retained.
• Generate both package-level and feature-level architecture reports.
• Add a feature classifier for producing the higher-level feature dependency view.
• Add tools/archmetrics_to_vega.py for transforming generated architecture metrics into documentation data and Vega-Lite visualisations.
• Add Vega-Lite visualisations for:
  • Abstractness vs Instability.
  • Distance from the Main Sequence.
  • Cross-feature dependency matrix.
• Add fineract-doc/src/docs/en/chapters/architecture/generated-package-overview.adoc, providing a generated section for each measured package and a consistent location for future architectural analysis.
• Add worked case studies covering different levels of cross-feature coupling and possible remediation approaches.
• Add guidance for deciding which feature dependencies are appropriate candidates for decoupling.
• Add documentation describing how cleaned module boundaries can be protected from regression.

The architecture metrics, generated documentation, and diagram data can be regenerated using:

./gradlew architectureMetricsReport

This PR primarily adds developer documentation and architecture-analysis tooling. There are no REST API, database schema, or externally visible behavioural changes.

Related JIRA: https://issues.apache.org/jira/browse/FINERACT-2757

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

• Write the commit message as per our guidelines
• Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
• Create/update unit or integration tests for verifying the changes made. — N/A: this PR adds developer documentation and architecture-analysis/build tooling rather than application behaviour. The generated architecture reports and documentation are produced through the Gradle architecture metrics task.
• Follow our coding conventions.
• Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes — N/A: no API changes.
• This PR must not be a "code dump". Large changes can be made in a branch, with assistance. Ask for help on the developer mailing list.
• If merging this PR resolves a JIRA issue, I will mark that issue as resolved and set "Fix Version/s" appropriately.

Your assigned reviewer(s) will follow our guidelines for code reviews.

[Copilot]

Pull request overview

This PR adds a reproducible architecture-metrics pipeline (generated from compiled bytecode via Gradle) and accompanying developer documentation/visualisations to analyze and explain cross-feature boundary violations as part of FINERACT-2757.

Changes:

• Introduces Gradle-based architecture metrics reporting (package-level and feature-level), plus tasks to regenerate documentation artifacts.
• Adds a Python transformer to turn the generated metrics JSON into Vega-Lite specs and an AsciiDoc “skeleton” reference.
• Adds extensive architecture documentation and commits the generated Vega-Lite diagram specifications used by the docs.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/archmetrics_to_vega.py	New CLI tool to transform architecture metrics JSON into Vega-Lite specs and generate AsciiDoc skeleton sections.
fineract-doc/src/docs/en/diagrams/main-sequence.vl.json	Adds a generated Vega-Lite spec for abstractness vs instability visualisation.
fineract-doc/src/docs/en/diagrams/distance-ranking.vl.json	Adds a generated Vega-Lite spec for distance ranking visualisation.
fineract-doc/src/docs/en/diagrams/cross-feature-matrix.vl.json	Adds a generated Vega-Lite spec for the cross-feature dependency matrix.
fineract-doc/src/docs/en/chapters/architecture/index.adoc	Wires the new cross-feature boundary violations chapter into the architecture docs index.
fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc	Adds the new detailed chapter describing CFVs, measurements, case studies, and regeneration guidance.
build.gradle	Adds and configures the java-architecture-metrics plugin plus aggregate/reporting/regen tasks to produce reports and docs artifacts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[vidakovic]

LGTM

[meonkeys]

Why do all the text lines in fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc wrap at ~85 characters? We use :hardbreaks: so each newline in the source forces a "carriage return", breaking automatic right margin during rendering for everything in the "Cross-Feature Boundary Violations" chapter.

Please take a look at fineract-doc/src/docs/en/chapters/architecture/batch-jobs.adoc vs. fineract-doc/src/docs/en/chapters/architecture/cross-feature-boundary-violations.adoc... we want all the asciidoc to use long lines and to let Asciidoctor handle line wrapping in PDF output and the browser to handle line wrapping in HTML output. Or we need to stop using :hardbreaks:, but I'm guessing that's more work.

:hardbreaks: is configured in fineract-doc/src/docs/en/config.adoc and documented in Hard Line Breaks.

See FINERACT-2795