Milestone 3.0 — Catalog-grounded AI architecture (decision record)
Status: Planned — applies to all EHX product surfaces, not a single technology (e.g. Kubernetes only).
Tracking: ehx-kb#12 · Epic: Phase 3 #6
Decision
The infrastructure assistant will not be a free-form “LLM writes infra from scratch” chat.
The target architecture is catalog-grounded AI orchestration:
| Layer | Responsibility | Source of truth |
|---|---|---|
| Conversation / reasoning | Understand messy requests, ask clarifying questions, route to the right product path | LLM + prompt orchestration |
| Retrieval | Find relevant packs, articles, suite playbooks, and variables | RAG over templates, modules, KB, suite narratives |
| Generation | Produce repeatable, reviewable artifacts | Deterministic render engine (M2.3 / M3.2) |
| Validation | Block or warn on unsafe output before export | Schema/policy checks (planned M3.6) |
| Product routing | Pricing, checkout, personas, plan entitlements | First-party routes + API (not hallucinated URLs) |
Core differentiator (roadmap): AI plus deterministic templates — LLM intent with validated, repeatable outputs.
What is live today (preview only)
| Milestone | Shipped | Limitation |
|---|---|---|
| M3.1 | Rule-based intent + suggestion links | No LLM; ~8 keyword intents |
| M3.2 | Fixed multi-file bundles for 5 intents | Static GENERATION_BUNDLES maps; starter v0.1 packs only |
| M2.3 | Single-file render + variables | Manual file pick on /generate |
These previews prove UX, API contracts, and analytics — they are not the final coverage model.
Product surfaces this architecture must cover
Generation and chat must eventually support every customer-facing catalog and suite, not only Kubernetes:
In-product catalogs (API-backed)
| Surface | Categories / sections | Notes |
|---|---|---|
Templates (/templates) | terraform, kubernetes, helm, monitoring, edge | Starter packs v0.1.0 |
Modules (/modules) | terraform, helm, monitoring, security | Composable packs v0.1.0 |
Knowledge base (/kb) | best-practices, deployment, troubleshooting | Guidance + checklists |
Generate (/generate) | templates + modules render | Single-file export today |
Suite offerings (marketing + evaluation narratives)
| Suite | Path | Domain |
|---|---|---|
| EHX Launch | /launch | Kubernetes deployment bundles |
| EHX Monitor | /monitor | Observability presets |
| EHX NodeOps | /nodeops | Web3 RPC, validators, chain ops |
| EHX Secure | /secure | Posture, exposure, security presets |
Commercial & onboarding flows
| Surface | Path | Role in chat |
|---|---|---|
| Get started / personas | /get-started | Route by role intent |
| Pricing | /pricing | Plan comparison, bundle mapping |
| Checkout | /checkout | Upgrade path (stub today) |
| Plan & usage | /account/plan | Entitlements after checkout |
Phase 4 expansion (Web3 intelligence)
Ethereum, OP Stack, validator, and RPC templates must plug into the same orchestration model — not a separate chat product.
Planned Phase 3 milestones (after M3.2 preview)
| Milestone | Goal | Key deliverables |
|---|---|---|
| M3.3 | Dashboard | Auth, saved projects, export history |
| M3.4 | LLM orchestration + RAG | Model provider wiring; retrieve from templates/modules/KB/suites; slot-filling (“environment?”, “ingress?”); llm_available: true |
| M3.5 | Composable catalog generation | Dynamic bundle assembly from catalog metadata (replace fixed intent maps); coverage matrix for all rows in this doc |
| M3.6 | Validation & safe export | Terraform/Helm/K8s schema checks; warnings before download; zip/multi-file export hardening |
M3.4 answers what the user meant and what to retrieve.
M3.5 answers which files to compose across all services.
M3.6 answers is this safe to apply.
Anti-patterns (do not ship)
- Raw LLM-generated Terraform/YAML with no catalog anchor
- One-off hard-coded bundle per use case (does not scale to full catalog breadth)
- Chat that invents pricing, checkout URLs, or entitlements
- Kubernetes-only orchestration while NodeOps / Secure / Launch remain link-only
Acceptance criteria (Phase 3 complete)
- User can describe a scenario in natural language for any catalog category or suite
- Assistant retrieves relevant packs/articles (RAG) and asks for missing slots
- Output is rendered from catalog files with applied variables
- Bundle composition is metadata-driven, not a fixed Python dict per intent
- Validation runs before export (minimum: syntax/schema warnings)
- Suite flows (Launch, Monitor, NodeOps, Secure) have explicit generation or guided paths
-
GET /chat/capabilitiesreflects real coverage, not a static subset
Phase 4 preview (same orchestration model)
| Milestone | Shipped | Notes |
|---|---|---|
| M4.1 | NodeOps packs v0.2.0 + web3_operations 8-file bundle | milestone-4-1-web3-templates.md |
| M4.2 | RPC health presets + web3_monitoring 8-file bundle | milestone-4-2-monitoring-intelligence.md |
| M4.3 | Security presets v0.2.0 + security_analysis 8-file bundle | milestone-4-3-security-analysis.md |
Related docs
- M3.1 — AI chat interface (preview)
- M3.2 — Infrastructure generation (preview)
- M4.1 — Web3 templates (preview)
- M2.3 — Generation API
- EHX Roadmap — Phase 3
- EHX Roadmap — Phase 4