# genaidevelopment/demo-hero-production-zero architecture

> Architecture diagram of the GitHub repository genaidevelopment/demo-hero-production-zero, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/genaidevelopment/demo-hero-production-zero
- Repository: https://github.com/genaidevelopment/demo-hero-production-zero

## Overview

This repository is a hands-on AI reliability workshop, not a deployed QuickBasket service. Its principal learning workflow moves from asking a policy question (prompt-only, then retrieval with citations) to giving a support agent narrowly scoped refund tools and checking whether its actions were safe. The map also preserves the documented help-centre generation and major knowledge domains. Notebook internals were not sampled, so notebook-to-runtime relationships are based on the README; unsampled implementation links are omitted.

Main entry points: [`quickbasket/kb_src/render.py`](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/render.py) (Document rendering), [`quickbasket/kb_src/common.py`](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/common.py) (KB facts and conflicts), [`quickbasket/build_kb.py`](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/build_kb.py) (Help-centre build), [`quickbasket/kb_src/faq.py`](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/faq.py) (Customer FAQ)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Workshop workflows"]
  node_myth1["Policy Q&amp;A"]
  node_myth2["Refund agent"]
end

subgraph group_knowledge["Knowledge base"]
  node_kbbuild["Help-centre build<br/>[build_kb.py]"]
  node_policy["Customer policies<br/>[policies.py]"]
  node_city["City addenda<br/>[cities.py]"]
  node_faq["Customer FAQ<br/>[faq.py]"]
  node_playbook["Agent playbook<br/>[playbook.py]"]
  node_promos["Promotions<br/>[promos.py]"]
  node_promo_detail["Promo details<br/>[promo_detail.py]"]
  node_terms["Membership terms<br/>[terms.py]"]
  node_sop["Partner SOP<br/>[sop.py]"]
  node_warranty["Warranty directory<br/>[warranty.py]"]
  node_kbcommon["KB facts and conflicts<br/>[common.py]"]
  node_render["Document rendering<br/>[render.py]"]
  node_chunker["Document chunking<br/>[kb_chunker.py]"]
  node_kbdocs["Help-centre documents"]
end

subgraph group_agent["Refund agent"]
  node_mcp["Narrow MCP tools<br/>[qb_mcp_server.py]"]
  node_orders[("Synthetic orders<br/>[quickbasket.db]")]
  node_audit["Refund safety audit<br/>[refund_audit.py]"]
end

subgraph group_shared["Shared runtime"]
  node_gemini["Gemini helpers<br/>[gemini_helpers.py]"]
  node_embeddings["Cached embeddings"]
  node_pricing["Pricing helpers<br/>[pricing.py]"]
end

node_participant(("Workshop participant"))

node_participant -->|"asks policy questions"| node_myth1
node_myth1 -->|"retrieves with citations"| node_kbdocs
node_participant -->|"tests refund requests"| node_myth2
node_myth2 -->|"uses narrow tools"| node_mcp
node_myth2 -->|"checks agent safety"| node_audit
node_kbbuild -->|"builds documents"| node_kbdocs
node_kbbuild -->|"imports policy data"| node_policy
node_kbbuild -->|"imports shared facts"| node_kbcommon
node_kbbuild -->|"imports renderers"| node_render
node_promos -->|"uses campaign details"| node_promo_detail
node_city -->|"imports shared facts"| node_kbcommon
node_city -->|"writes documents"| node_render
node_faq -->|"uses city data"| node_city
node_faq -->|"uses warranty data"| node_warranty
node_faq -->|"uses rendering"| node_render
node_playbook -->|"imports shared facts"| node_kbcommon
node_playbook -->|"uses rendering"| node_render
node_sop -->|"imports shared facts"| node_kbcommon
node_sop -->|"uses rendering"| node_render
node_warranty -->|"imports shared facts"| node_kbcommon
node_warranty -->|"uses rendering"| node_render
node_embeddings -->|"calls retry helper"| node_gemini

click node_myth1 "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/myth1_prompt_is_enough.ipynb"
click node_myth2 "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/myth2_agent_with_tools.ipynb"
click node_kbbuild "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/build_kb.py"
click node_policy "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/policies.py"
click node_city "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/cities.py"
click node_faq "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/faq.py"
click node_playbook "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/playbook.py"
click node_promos "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/promos.py"
click node_promo_detail "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/promo_detail.py"
click node_terms "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/terms.py"
click node_sop "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/sop.py"
click node_warranty "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/warranty.py"
click node_kbcommon "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/common.py"
click node_render "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/render.py"
click node_chunker "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_chunker.py"
click node_kbdocs "https://github.com/genaidevelopment/demo-hero-production-zero/tree/main/quickbasket/kb"
click node_mcp "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/qb_mcp_server.py"
click node_orders "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/quickbasket.db"
click node_audit "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/refund_audit.py"
click node_gemini "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/common/gemini_helpers.py"
click node_embeddings "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/common/cached_embeddings.py"
click node_pricing "https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/common/pricing.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_myth1,node_myth2 toneBlue
class node_kbbuild,node_policy,node_city,node_faq,node_playbook,node_promos,node_promo_detail,node_terms,node_sop,node_warranty,node_kbcommon,node_render,node_chunker,node_kbdocs toneAmber
class node_mcp,node_orders,node_audit toneMint
class node_gemini,node_embeddings,node_pricing toneRose
class node_participant toneIndigo
```

## Components

### Workshop workflows

- [Policy Q&A](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/myth1_prompt_is_enough.ipynb): `quickbasket/myth1_prompt_is_enough.ipynb`
- [Refund agent](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/myth2_agent_with_tools.ipynb): `quickbasket/myth2_agent_with_tools.ipynb`

### Knowledge base

- [Help-centre build](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/build_kb.py): `quickbasket/build_kb.py`
- [Customer policies](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/policies.py): `quickbasket/kb_src/policies.py`
- [City addenda](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/cities.py): `quickbasket/kb_src/cities.py`
- [Customer FAQ](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/faq.py): `quickbasket/kb_src/faq.py`
- [Agent playbook](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/playbook.py): `quickbasket/kb_src/playbook.py`
- [Promotions](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/promos.py): `quickbasket/kb_src/promos.py`
- [Promo details](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/promo_detail.py): `quickbasket/kb_src/promo_detail.py`
- [Membership terms](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/terms.py): `quickbasket/kb_src/terms.py`
- [Partner SOP](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/sop.py): `quickbasket/kb_src/sop.py`
- [Warranty directory](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/warranty.py): `quickbasket/kb_src/warranty.py`
- [KB facts and conflicts](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/common.py): `quickbasket/kb_src/common.py`
- [Document rendering](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_src/render.py): `quickbasket/kb_src/render.py`
- [Document chunking](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/kb_chunker.py): `quickbasket/kb_chunker.py`
- [Help-centre documents](https://github.com/genaidevelopment/demo-hero-production-zero/tree/main/quickbasket/kb): `quickbasket/kb`

### Refund agent

- [Narrow MCP tools](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/qb_mcp_server.py): `quickbasket/qb_mcp_server.py`
- [Synthetic orders](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/quickbasket.db): `quickbasket/quickbasket.db`
- [Refund safety audit](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/quickbasket/refund_audit.py): `quickbasket/refund_audit.py`

### Shared runtime

- [Gemini helpers](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/common/gemini_helpers.py): `common/gemini_helpers.py`
- [Cached embeddings](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/common/cached_embeddings.py): `common/cached_embeddings.py`
- [Pricing helpers](https://github.com/genaidevelopment/demo-hero-production-zero/blob/main/common/pricing.py): `common/pricing.py`

### Other components

- **Workshop participant**

## Connections

- Workshop participant → Policy Q&A: asks policy questions (evidence: `README.md`)
- Policy Q&A → Help-centre documents: retrieves with citations (evidence: `README.md`)
- Workshop participant → Refund agent: tests refund requests (evidence: `README.md`)
- Refund agent → Narrow MCP tools: uses narrow tools (evidence: `README.md`)
- Refund agent → Refund safety audit: checks agent safety (evidence: `README.md`)
- Help-centre build → Help-centre documents: builds documents (evidence: `README.md`)
- Help-centre build → Customer policies: imports policy data (evidence: `quickbasket/build_kb.py`)
- Help-centre build → KB facts and conflicts: imports shared facts (evidence: `quickbasket/build_kb.py`)
- Help-centre build → Document rendering: imports renderers (evidence: `quickbasket/build_kb.py`)
- Promotions → Promo details: uses campaign details (evidence: `quickbasket/kb_src/promos.py`)
- City addenda → KB facts and conflicts: imports shared facts (evidence: `quickbasket/kb_src/cities.py`)
- City addenda → Document rendering: writes documents (evidence: `quickbasket/kb_src/cities.py`)
- Customer FAQ → City addenda: uses city data (evidence: `quickbasket/kb_src/faq.py`)
- Customer FAQ → Warranty directory: uses warranty data (evidence: `quickbasket/kb_src/faq.py`)
- Customer FAQ → Document rendering: uses rendering (evidence: `quickbasket/kb_src/faq.py`)
- Agent playbook → KB facts and conflicts: imports shared facts (evidence: `quickbasket/kb_src/playbook.py`)
- Agent playbook → Document rendering: uses rendering (evidence: `quickbasket/kb_src/playbook.py`)
- Partner SOP → KB facts and conflicts: imports shared facts (evidence: `quickbasket/kb_src/sop.py`)
- Partner SOP → Document rendering: uses rendering (evidence: `quickbasket/kb_src/sop.py`)
- Warranty directory → KB facts and conflicts: imports shared facts (evidence: `quickbasket/kb_src/warranty.py`)
- Warranty directory → Document rendering: uses rendering (evidence: `quickbasket/kb_src/warranty.py`)
- Cached embeddings → Gemini helpers: calls retry helper (evidence: `common/cached_embeddings.py`)
