docs(arc42): federated catalogue — content verification and decoupling sweep#45
Open
noVaSon wants to merge 3 commits into
Conversation
…ementation detail Sweep the official architecture documentation under docs/federated-catalogue/ to make it durable against implementation churn: - terminology: title and lead use XFSC; GXFS retained only as dated historical provenance; new glossary entry for GXFS vs XFSC; Loire vs Danube + danubetech library naming collision clarified in Ch.4 - references: Gaia-X links pinned per Loire sub-document (Architecture 25.05, ICAM 24.07, Compliance 25.10, Data Exchange 25.07, Ontology 25.11), no /latest/; cross-repo example links absolute and verified against origin/main; example credential timestamps replaced with illustrative placeholders - decoupling: SQL DDL tables, Liquibase changeset IDs, sequence names, HTTP status codes, property-name=value pins, and inline OpenAPI paths in prose replaced with conceptual descriptions; Ch.7 references the wiki Installation & Configuration Guide as the canonical config source - ADR hygiene (Ch.9): SRS story IDs, internal PR numbers, `admin_config` column references, and property-name pins removed in favour of concept statements; ADR-4 enrichment rewritten free of column-level detail
Final readability pass over the federated-catalogue architecture docs: - add or strengthen chapter leads (Ch.2, 3, 4, 5, 8, 9, 10) - fix broken/non-standard internal xrefs and an anchor typo - repair a garbled section opener in Ch.6 - explain the ADR numbering gap (10 → 15) in Ch.9 - mark Ch.1 historical assumptions as provenance, not current spec - extend the glossary with SRS, EVC/EVP, Audit Shadow, Provenance Credential, and RDF-star - add a glossary pointer and inline glosses in Ch.4 for forward terms
- Ch.5: add forward pointers for RoutingGraphStore/GraphStore, baseClass + trust-framework bundle, and RdfClaim - Ch.7: replace the Keycloak admin-UI cookbook (realm directories, iframe headers, console URL override) with a 4-point architectural framing and a link to the wiki Admin Guide - wiki: extend FC-Administration-Guide with the carved-out Keycloak realm + iframe-header + Admin Console URL procedures
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🚀 Summary
Sweep across the arc42 architecture document for the federated catalogue to make it more durable as a reference for new contributors and maintainers. Three passes were applied in order: (1) decouple the prose from implementation detail — SQL DDL, Liquibase changeset names, HTTP status codes in prose,
federated-catalogue.*=valueproperty pins,/latest/Gaia-X links — replaced with conceptual descriptions that point at the OpenAPI spec, the wiki Installation & Configuration Guide, and the Liquibase changelog as the actual sources of truth; (2) a linear-readability pass that added chapter leads, fixed a handful of broken<<…>>cross-references and an anchor typo, repaired a garbled section opener in chapter 6, documented the gap in ADR numbering (10 → 15), and extended the glossary with SRS, EVC/EVP, Audit Shadow, Provenance Credential, and RDF-star entries; (3) follow-up work on out-of-order definitions in chapter 5 (forward pointers toGraphStore, the trust-framework-bundle / base-class concept, andRdfClaim) and a carve-out of the Keycloak operator cookbook from chapter 7 into the wiki Administration Guide, leaving a four-point architectural framing behind.Side effects: Gaia-X external links pinned per Loire sub-document (Architecture 25.05, ICAM 24.07, Compliance 25.10, Data Exchange 25.07, Ontology 25.11) so a future Gaia-X release does not silently reinterpret statements authored against Loire; appendix example-query links repaired and verified against the source repository; example credential timestamps replaced with illustrative placeholders; the Loire / Danube / `danubetech` library naming collision is now disambiguated in chapter 4.
✅ What's Changed
🧪 How to Test
🔍 Related Issues
Closes #
Related to #
📸 Screenshots (if applicable)
📋 Checklist