Align project with architecture-knowledge-toolkit (reference model, arc42 migration, docs CI) - #2
Merged
Conversation
- Replace flat src/docs/adr/*.md and architecture.adoc with full arc42 chapter structure under src/docs/arc42/ (ADRs, quality scenarios, risks, technical debt) plus generated traceability views - Add architecture-knowledge-toolkit metamodel contracts (metamodel/artifact.schema.yaml, relations.schema.yaml) and Ruby metamodel validation script + tests under scripts/ - Add Gradle multi-module build (root + per-module build.gradle, settings.gradle) - Add vision-mission, roadmap, questions-and-answers docs - Refresh AGENTS.md and README for the toolkit conventions; remove PROJECT_SUMMARY.md - Minor updates to Java sources across modules Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Adopt the toolkit's current consuming-project model: vendor only the executable tooling and reference the toolkit for skills and contracts. Vendored/synced from the toolkit: - metamodel/artifact.schema.yaml, relations.schema.yaml (adds derived_from, new DOC decimal ID examples) - scripts/validate-metamodel.rb (adds deterministic generation) - templates/adr.adoc, quality-scenario.adoc, risk.adoc - scripts/build-agent-adapters.js, check-agent-adapters.js (generic generator) Reference model (skills/contracts not copied): - Rewrite AGENTS.md from the toolkit project-agents template: thin contract order, toolkit lookup order, reference-don't-copy, adapter wiring; keep only a short project-context delta and point to src/docs for the rest - Add .github/copilot-instructions.md entry point - Generate adapters/ (codex, vibe, github-copilot, cursor) via the generator Derived output: - Ignore **/generated/, target/, out/ and untrack committed generated fragments - Rename questions-and-answers.adoc -> doc-005-questions-and-answers.adoc to match the toolkit inception filename (unblocks generation) Fix relation metamodel violations: 'informs' -> 'relates_to' in vision-mission and roadmap. Remove dead vendored validator test (no fixtures; the toolkit owns validator tests). validate + generate now pass (0 errors; 28 filename warnings remain for the older artifact ID scheme, tracked as a follow-up content migration). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Bring the existing documentation to the shape a fresh toolkit bootstrap would produce: - Renumber chapter IDs to the DOC-0XX00 decimal scheme (DOC-101 -> DOC-01000, ... DOC-111 -> DOC-11000); entry DOC-000 -> DOC-001; root inception docs -> DOC-002-vision-mission, DOC-004-roadmap - Rename every source file to match its normalized ID: chapter overviews to doc-0XX00-*.adoc, entry to doc-001-arc42.adoc, and lowercase the adr-*/risk-*/td-* detail files - Fix artifact types: ArchitectureDecision -> ADR, DocumentSet -> Document - Fix `.tags:` YAML key typo -> `tags:` across 25 files - Update all relation targets, includes, and xrefs to the new IDs/filenames; add the missing arc42/ include prefix and leveloffset in the entry point Validator now reports 0 errors and 0 warnings; generate succeeds. Known follow-up (pre-existing content gaps, not introduced here): some xrefs point to quality-scenario (QS-*) and canvas artifacts that were never authored. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Add a project task runner modeled on the toolkit's reference build.sh. By default it runs inside the pinned docs-as-code-toolkit/docs-toolbox image (Docker/Podman) so local and CI runs share one reproducible toolchain; DOCS_TOOLBOX_LOCAL=1 falls back to the host toolchain. Tasks: validate, generate, adapters, check-adapters, build (renders build/architecture/index.html from src/docs/doc-001-arc42.adoc), all, clean. Java modules stay on ./gradlew (docs-toolbox has no JDK). Also fix invalid PlantUML in the building-block view: semantic-anchor annotations inside the @startuml block broke rendering under --failure-level=ERROR. The anchors remain as AsciiDoc prose below the diagram. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
- .github/workflows/ci.yml: on pull_request and pushes to main, validate architecture metadata/relations, run the generator (reproducibility), and check agent adapters are current — all via ./build.sh in the pinned docs-toolbox image; plus a Java job (JDK 21 + Gradle 8.5) running gradle build. - .github/workflows/pages.yml: on main, render the arc42 HTML with ./build.sh build (docs-toolbox) and deploy build/architecture to GitHub Pages. - adapters/agent-adapters.config.json: pin the adapter project name to event-processing-lab so check-adapters is stable regardless of the CI checkout directory name. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
- Author QS-001..QS-015 as QualityScenario artifacts under src/docs/arc42/10-quality-requirements/ using the toolkit six-part template, each tracing to the quality goal it concretizes. These were referenced by the chapter 10 index and by risk/TD xrefs but the files never existed. - Fix chapter 10 to actually include them: `Include::` -> `include::` and QS- -> qs- filenames; lowercase the QS xref paths in the risk/TD detail files. - Remove all canvas references (this project has no canvases): xref bullets, a risk traceability row each in risk-003 and risk-006, canvas semantic-anchors, and the business-context-diagram pointer in chapter 3. - Repair adjacent broken prose xrefs to the introduction chapter exposed while editing (uppercase DOC-*.adoc id-form links -> correct doc-*.adoc paths). Validator: 46 artifacts, 0 errors, 0 warnings. ./build.sh build renders the full arc42 HTML cleanly (all QS includes and generated fragments resolve). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Update the project front door to match the current layout: - Correct the src/docs tree: doc-001-arc42.adoc entry, doc-0XX00 chapter sources, lowercase adr-*/risk-*/td-* and the new qs-* detail files; add the vendored metamodel/, templates/, scripts/, adapters/, and .github/ tooling. - Fix the Java module layout (modules live at the repository root, not under a modules/ directory) and drop the non-existent 12-glossary entry. - Repoint all architecture-doc links to the new doc-001/doc-0XX00 filenames and remove references to canvases the project does not have. - Add a "Validating and building the documentation" section describing ./build.sh validate|generate|build and the CI + GitHub Pages workflows. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
The flink-cep module never compiled. Repair it so `gradle build` (and the CI Java job) passes: - Add missing imports: org.apache.flink.api.java.functions.KeySelector and org.apache.flink.util.Collector. - Remove invalid `.build()` calls on Flink CEP Pattern chains (the Pattern API has no build(); the chain already yields the Pattern). The KafkaSource builder's build() is unchanged. - Restore the commented-out createOrderCreationPattern() that buildJob() calls. - Remove the dead, non-compiling SameOrderCondition (unused; relied on a non-existent IterativeCondition.Context.getEvents()). - Declare `throws Exception` on start()/main() for env.execute(). Verified locally with `gradle build` (exit 0). This fixes compilation only; runtime CEP behavior is still unverified — covered by the new roadmap item to add unit tests for the implementations. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Move architectural content out of the README and into the arc42 docs, and address anchor rendering: - README: keep only overview, setup, running components, and a new "Running a use case to evaluate the Comparison Matrix" guide; replace the duplicated architecture sections (learning objectives, quality goals/scenarios, runtime scenarios, comparison matrix, focus areas, risks, conventions) with links into src/docs. Drop the now-empty Semantic Anchors section. - Ch4 Solution Strategy: add the Comparison Matrix and comparison dimensions (previously only in the README) as reviewable content with anchors. - Remove all [semantic-anchor: ...] markers from the documentation (242 occurrences). They leaked into rendered headings, list items, and tables and duplicated the toolkit's metadata-relation model. Real AsciiDoc [[anchors]] are kept; verified the rendered HTML contains no [semantic-anchor] text and no raw [[...]] leakage, with no Asciidoctor reference warnings. - Roadmap: expand Phase 4 to add unit tests for the implementations and Gherkin behaviour specs bridged to tests (bdd-specification skill); add a Phase 5 "Comparison Matrix Dashboard" for the evaluation metrics. - Add features/order-lifecycle-processing.feature as living documentation for the shared use case (test bridge pending, per roadmap Phase 4). Validator: 46 artifacts, 0 errors, 0 warnings. ./build.sh build renders cleanly. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
dieterbaier
commented
Jul 12, 2026
dieterbaier
left a comment
dieterbaier
left a comment
Owner
Author
There was a problem hiding this comment.
Die Toolkit-/arc42-Migration ist insgesamt schlüssig und die CI ist grün. Ich habe einen technischen Punkt im Java-Build kommentiert, der vor dem Merge geklärt werden sollte: Das Flink-CEP-Modul mischt Flink-Core/Streaming 1.14.6 mit Flink CEP 1.15.0. Ein erfolgreicher Compile beweist hier leider keine Laufzeitkompatibilität; Gradles Versionsauflösung kann dabei still Teile auf 1.15 ziehen. Bitte die Flink-Artefakte auf eine gemeinsame Version bringen oder die bewusst gemischte Kombination mit einem ausführbaren Integrationstest absichern.
| kafkaVersion = '3.6.1' | ||
| kafkaClientsVersion = kafkaVersion | ||
|
|
||
| // Esper dependencies [semantic-anchor: technology.esper] |
Owner
Author
There was a problem hiding this comment.
Bitte vereinheitlichen: flinkVersion = 1.14.6 und flinkCepVersion = 1.15.0 werden im flink-cep-Modul gemeinsam verwendet. Dadurch landen Core/Streaming/Kafka-Connector und CEP aus unterschiedlichen Flink-Releases im selben Runtime-Classpath; Gradle kann Transitives still auflösen, aber API-/Binärinkompatibilitäten zeigen sich dann erst beim Start oder bei Pattern-Ausführung. Am sichersten ist eine einzige Flink-Version für alle Flink-Artefakte. Falls die Mischung absichtlich nötig ist, sollte mindestens ein Test den CEP-Job tatsächlich initialisieren und ein Pattern ausführen.
flink-cep pulled flink-cep 1.15.0 while flink-core/streaming/connector were
1.14.6, mixing two Flink releases on one runtime classpath. Standardize on a
single release: drop flinkCepVersion and depend on
org.apache.flink:flink-cep_2.12:${flinkVersion} (1.14.6), matching the Scala
suffix and version of the other Flink artifacts. Verified with gradle build.
A CEP job that initializes and executes a pattern at runtime is covered by the
Phase 4 roadmap item (unit/behaviour tests for the implementations).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Owner
Author
|
Addressed in 5544304: unified all Flink artifacts on a single release. Dropped |
dieterbaier
commented
Jul 12, 2026
dieterbaier
left a comment
dieterbaier
left a comment
Owner
Author
There was a problem hiding this comment.
Nachprüfung der Änderung: Das ursprüngliche Finding ist sauber behoben. Alle Flink-Artefakte im CEP-Modul verwenden jetzt konsistent flinkVersion = 1.14.6, einschließlich passendem _2.12-Suffix. Die aktuelle CI ist grün. Keine neuen Findings in der Nachbesserung.
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.
Aligns Event Processing Lab with the current
docs-as-code-toolkit/architecture-knowledge-toolkit"reference, don't copy"model — as if the project had been bootstrapped with today's toolkit while
keeping its existing implementation and documentation.
What changed
Toolkit alignment (reference model)
validate-metamodel.rb(now with generation), ADR/quality-scenario/risk templates, and the generic
agent-adapter generator.
AGENTS.mdfrom the toolkitproject-agentstemplate — thin contractorder + toolkit lookup order; project delta points at
src/docs/instead ofrestating toolkit rules.
.github/copilot-instructions.mdentry point and generate thinadapters/(codex, vibe, github-copilot, cursor); pin the adapter projectname via
adapters/agent-adapters.config.json.**/generated/,build/, and untrackthe previously committed generated fragments.
arc42 content migration to the toolkit scheme
DOC-0XX00decimal scheme and rename every sourcefile to its normalized ID (
doc-001-arc42.adoc,doc-0XX00-*chapters,lowercase
adr-*/risk-*/td-*).ArchitectureDecision→ADR,DocumentSet→Document), the.tags:typo, and all relation targets/xrefs/includes.qs-001…qs-015) that neverexisted, and remove all canvas references (the project has no canvases).
Tooling & CI
build.sh: a docs-toolbox task runner (validate/generate/build) modeledon the toolkit's reference implementation.
ci.yml: validate + generate + adapter check (in docs-toolbox) and a Javabuild/test job on every PR and on
main.pages.yml: render the arc42 HTML and publish to GitHub Pages onmain.README.mdfor the new structure, links, and doc build commands.Verification
./build.sh validate→ 46 artifacts, 0 errors, 0 warnings../build.sh buildrendersbuild/architecture/index.htmlcleanly under--failure-level=ERROR(all includes and generated fragments resolve).Related
generic
templates/scripts/build.shand bootstrap/README guidance, since thetoolkit did not yet tell consuming projects to install such a script.
🤖 Generated with Claude Code