About These Visual Guides
Interactive visual documentation to help understand the Konflux CI/CD platform and infra-deployments repository.
What Are These Guides?
Self-contained interactive HTML pages with:
- 📊 Animated diagrams and flowcharts
- 🔍 Searchable component directories
- 📱 Mobile-responsive design
- 🎨 Color-coded categories and difficulty levels
They complement the text documentation by providing visual explanations of complex workflows.
How Were These Guides Created?
These guides were generated using AI assistance in a Cursor workspace that had multiple Konflux-related repositories cloned together:
redhat-appstudio/infra-deployments- The main deployment manifestskonflux-ci/e2e-tests- End-to-end test suites and rules engineopenshift/release- OpenShift CI configuration and job definitionskonflux-ci/architecture- System architecture documentation- Various component repositories (build-service, integration-service, etc.)
Why does this matter? Many workflows involving infra-deployments span multiple repositories. For example:
- The test selection rules that run on infra-deployments PRs are defined in
e2e-tests - The CI job configuration lives in
openshift/release - Component behavior that drives manifest changes is in the component repos
Having all these repos in the same workspace allowed the AI to research across the entire ecosystem and accurately describe how things work end-to-end, not just what’s visible in infra-deployments alone.
To update or create guides with full context, clone the related repos into your workspace before asking your LLM to make changes.
🤖 Contributing with AI Assistance
These guides are designed to be maintained and extended with LLM assistance (Cursor, Copilot, Claude, etc.).
Updating Existing Guides
When you make changes to infra-deployments that might affect a visual guide:
Tell your LLM:
“I just made changes to [describe your changes]. Check if any visual learning guides in
docs/misc/visual-learning-guides/need to be updated. Reference the style guide indocs/misc/visual-learning-guides/style-guide-for-llms.mdand the existing HTML files in that directory to maintain consistency.”
What changes trigger updates:
| Your Change | Guide to Update |
|---|---|
New component in components/ |
visual-components-map.html |
| New Kustomize overlay | visual-kustomize-overlays.html |
| CI/testing config changes | visual-testing-flow.html, visual-e2e-infra-tests.html |
| PR pairing syntax changes | visual-pr-pairing.html |
| Renovate/MintMaker changes | visual-renovate-workflow.html |
| Deployment pipeline/ArgoCD changes | visual-pr-workflow.html |
Current guides:
index.html- Landing page with cards linking to all guidesvisual-components-map.html- Searchable component directoryvisual-kustomize-overlays.html- How Kustomize overlays workvisual-testing-flow.html- Complete E2E testing flowvisual-e2e-infra-tests.html- Test selection rules for infra-deployments PRsvisual-pr-pairing.html- How to pair PRs across repos (Prow-specific)visual-pr-workflow.html- Animated PR-to-production timelinevisual-renovate-workflow.html- MintMaker/Renovate automation
Creating New Guides
To add a new visual learning guide:
Tell your LLM:
“Create a new visual learning guide about [your topic]. Read
docs/misc/visual-learning-guides/style-guide-for-llms.mdfor the style guide and color palette. Use the existing HTML files in that directory as reference for structure and patterns. Research the relevant code in this repository, then generate a new HTML file following the same patterns.”
The LLM should:
- Read
docs/misc/visual-learning-guides/style-guide-for-llms.mdfor the style guide - Read 2-3 existing HTML files in that directory to understand patterns
- Research the topic in the codebase
- Generate a new HTML file with consistent styling
- Update
docs/misc/visual-learning-guides/index.htmlto add a card for the new guide
📋 Style Guide (For LLMs)
For detailed technical reference on colors, typography, code blocks, and patterns to use when generating or updating guides, see: