Docs: Fill README CI/CD gap, note LLM_API_KEY, and fix doc rot

[DoPri]

What does this PR do?

A few documentation gaps and some doc rot that reviewers kept tripping over. All docs, no code.

• README quickstart now mentions LLM_API_KEY. A cold docker compose up boots a working app, but every GenAI feature (summary, tags, entity extraction, semantic search, Q&A) errors until an LLM key is set. That was only explained in .env.example and the genai README, not where a tutor actually starts. Added a short note to the quickstart and flagged the key as the one env var without a usable default.
• README now has a CI/CD section. The requirement is that the README covers CI/CD, and so far that only lived in System_Overview.md and the infra READMEs (the root had badges plus links). Added a short section describing what CI runs on a PR and what CD does on a push to main, with links to the workflows.
• Documented that the Spring GenAI client is generated. services/spring/README.md now spells out that com.alexandria.genai.client.* (the AiApi GenAiClient wraps) is produced by the Gradle openApiGenerate task from api/openapi.yaml, not hand-written, and must not be edited by hand. Note the mechanism is the Gradle build (wired to compileJava); the pre-commit hooks keep the spec it generates from in sync.
• Fixed two stale bits in System_Overview.md. The realm path was oidc/realm.json (actually infra/oidc/realm.json), and it claimed "one Dockerfile per component" which isn't true: the three Spring services share one parameterised Dockerfile and the DB/infra run from stock images. Reworded to match reality.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Docs
• CI / infra

Definition of Done

• CI is green
• If the API changed: api/openapi.yaml is updated and lint passes
• If a service was added or restructured: docker-compose still comes up cleanly (docker compose up)
• Tests added or updated for the changed behaviour
• Docs updated where it matters (README, ADRs, comments)

Notes for the reviewer

Summary by CodeRabbit

• Documentation
  • Clarified environment variable setup, including requirements for GenAI features and .env configuration.
  • Added CI/CD documentation covering automated checks, image publishing, API documentation, and Kubernetes/Azure deployments.
  • Updated architecture documentation with clearer service responsibilities, infrastructure details, deployment targets, and UML diagrams.
  • Expanded GenAI integration documentation, including generated client models and build workflow details.
  • Improved formatting and readability across service architecture, endpoints, metrics, and deployment sections.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation is updated for GenAI environment requirements, CI/CD workflows, system architecture and deployment, UML diagrams, Spring microservice routing, and generated GenAI client models.

Changes

Documentation updates

Layer / File(s)	Summary
Configuration and CI/CD documentation README.md	Documents the required LLM_API_KEY, GenAI configuration references, CI/CD workflows, image publishing, deployment targets, security scanning, and API documentation publishing.
Architecture and infrastructure documentation docs/System_Overview.md	Reorganizes service descriptions and UML sections, updates the Keycloak realm path, and documents Docker, Helm, Terraform, Ansible, and CI details.
Spring service documentation services/spring/README.md	Reformats architecture and endpoint tables and documents GenAI processing behavior, generated client models, Gradle task ordering, and OpenAPI synchronization.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• AET-DevOps26/team-bnd#340: Updates overlapping README and system architecture documentation.

Suggested labels: ci/cd, genai, infrastructure

Suggested reviewers: bjarneha, ladu-tu

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the docs-only changes to README, CI/CD, LLM_API_KEY, and doc cleanup.
Description check	✅ Passed	The description follows the template, explains the changes, includes type and done sections, and is mostly complete.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/root-readme-and-doc-fixes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/System_Overview.md`:
- Line 100: Update the deployment-trigger wording in the system overview
paragraph to state that GitHub Actions deploys on pushes to main, replacing the
current merge-only wording while leaving the rest of the CI description
unchanged.

In `@README.md`:
- Around line 48-52: Update the README’s GenAI feature description to
distinguish semantic search from AI enrichment: without LLM_API_KEY, document
summaries, tag extraction, entity extraction, and Q&A return errors, while
semantic search falls back to keyword results as documented in
services/spring/README.md. Keep the environment setup and configuration guidance
unchanged.

In `@services/spring/README.md`:
- Around line 27-28: Update the README processing documentation to state that
only summary, entities, and tags have reprocess endpoints; replace the broader
“Every step” wording without implying indexing can be reprocessed. Keep the
existing route list and tag behavior description unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6060b66d-3243-43e8-8d71-bcbf872b59bd

📥 Commits

Reviewing files that changed from the base of the PR and between e76d670 and ac033dd.

📒 Files selected for processing (3)

• README.md
• docs/System_Overview.md
• services/spring/README.md