Add architecture documentation and CI/CD best practices

[sauagarwa]

Summary

• Add comprehensive ARCHITECTURE.md covering what Red Hat AI Quickstarts are, the OpenShift AI platform features they leverage, the shared AI Architecture Helm Charts library, and how to create a new quickstart
• Add testing best practices: unit tests, integration tests, LLM evaluation framework (DeepEval), Helm chart validation
• Add code quality standards: flake8, black/isort, mypy strict mode, custom structured logging rules
• Add git workflow guidance: dev/main branch promotion, version management, dependency management with uv, container build patterns
• Add GitHub Actions CI/CD pipeline templates: PR checks, e2e tests, nightly evaluation, build/push, promotion workflows
• Add docs/index.md with navigable links to all architecture sections

Test plan

• Review ARCHITECTURE.md for accuracy and completeness
• Verify all links to ai-architecture-charts and sample repos are correct
• Validate Helm chart examples match current chart patterns
• Review GitHub Actions workflow templates for correctness

🤖 Generated with Claude Code

[sarabanderby]

Following information is duplicate:

• Information about what AI quickstarts are. This already exists in 3 places across the repo 🙂
• Repository requirements -> CONTRIBUTING.md contains all requirements already that has been decided and should be the source of truth. With the exception of PUBLISHING.md that has extra requirements for how to get published on redhat.com, there should be one source of truth to avoid conflicting or duplicate information.
• The template requirements already exists in the template repo and how to use it.
• Description already exists.

My thoughts:

• MinIO is mentioned here but it has had a license change AND the upstream is in maintenance mode. Given the licensing change and upstream maintenance status, I would be cautious about listing MinIO as a key technology component. It is mentioned under Key Technology Components. Also, many other quickstarts may not use the components listed in this PR. We are not wanting to limit or push contributors to using a specific technology. The main technologies are OpenShift and OpenShift AI. The most interesting thing is how to solve a business problem, not necessarily what database was used even though certain users will find that more interesting.
• Llamastack is mentioned, it is no longer its name. The name is OGX and this would need to be changed.
• Architecture slide is already a requirement under the template README.md but we don't give a template for it at the moment so that might be a nice addition to the template repo, as long as it can be incorporated in the README.md 😄
• In the pr-checks.yaml it seems that all checks will run in ubuntu-latest. Is that your intention?

Questions from me:

• Since much of this information already exists elsewhere in the repository, was it unclear in the contributing repo or hard to find as a builder from the entry point in GitHub? If it was, then I might need to change the structure. At the moment, this PR reads more like a standalone contribution guide than an extension of the existing one, and some of the standards appear to differ from the current contribution guide.
• It looks like we are enforcing Helm as a standard in this PR. We currently have repos and users not using Helm and if this is a requirement they are going to have to rebuild their quickstarts. I was under the impression this was not decided yet. Please correct me if this is wrong.
• It mentions Project Navigator integrations, this is not finished or exist yet does it?
• It says all AI quickstarts are built on RHOAI, which is not true. There are many quickstarts in the repo that are not.
• There are added PR evaluation checks, but I'm under the impression work is already underway to build validation that won't require users to build things differently. Please correct me if I'm wrong. Can you have a look at the files and see so we are not doing duplicate work? Also, the work Yoni and Adam are doing.

My recommendation is to align this PR with the existing contribution guide and user guide, removing duplicated requirements and updating the source documentation where additional guidance is needed. 🙂 For example, having a template architecture MD that they can start using is awesome.

I will leave comments about the automated checks since that has been what others have been working on, as well as Adam and Yoni using agentic AI to run validation without requiring users or contributors to necessarily redo their existing work.

[johnson2500]

• So far first look my suggestion would be to break this ARCHITECTURE.md file into a few slices. Maybe split based on the docs/index.md file.

[mhdawson]

There is a lot of good content in here, main comment is that there might be a bit too much specific detail to start with. Maybe sections with less content, but then references to examples of how things were implemented. The maybe more specific requirements/details once we prove things out on 2 or more quickstarts ?

[johnson2500]

I left a few comments on the PR, over all it looks good. I assume this is going to be out starting point and hopefully this will be cloned as a part of the quickstart factory?

[johnson2500]

I left a few comments on the PR, over all it looks good. I assume this is going to be out starting point and hopefully this will be cloned as a part of the quickstart factory?

I just want to ensure that we do not have a bunch of sprawl.

[mhdawson]

We probably want to pull out Llama Guard/Prompt Guard since those are no longer in OGX, but it is accurate for existing Quickstarts

[mhdawson]

This does reflect what we do in the it-self-service-agent (using Kind for a number of the runs), but I'm not sure we want that in the doc here as any quickstart that a usable subset cannot be deployed without OpenShift AI would not be able to do this.