# 1012-penn/shophelperv2 architecture

> Architecture diagram of the GitHub repository 1012-penn/shophelperv2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/1012-penn/shophelperv2
- Repository: https://github.com/1012-penn/shophelperv2

## Overview

MewHelp is an e-commerce customer-support application centered on persistent, streaming chat. For each user turn, FastAPI routes the request to chat orchestration, which can answer with knowledge-backed evidence or invoke business tools; conversations and results are persisted, and citations can link to source text. Separate product capabilities include after-sale extraction and ingestion of documents or conversations into the knowledge base. The README also documents hybrid retrieval, quality controls, and evaluation; unsampled subsystem links are shown only where documented, with evidence limits noted.

Main entry points: [`app/services/quality/runtime.py`](https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/runtime.py) (Answer runtime), [`app/services/knowledge/embeddings.py`](https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/embeddings.py) (Embedding client), [`app/main.py`](https://github.com/1012-penn/shophelperv2/blob/main/app/main.py) (HTTP application), [`app/services/quality/retrieval.py`](https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/retrieval.py) (Evidence retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and API"]
  node_workbench["Support workbench<br/>[App.jsx]"]
  node_http["HTTP application<br/>[main.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
end

subgraph group_chat["Support workflow"]
  node_chat["Chat orchestration<br/>[chat.py]"]
  node_after_sale["After-sale extraction<br/>[after_sale.py]"]
  node_tools["Business tools<br/>[registry.py]"]
  node_business["Order operations<br/>[business.py]"]
end

subgraph group_knowledge["Knowledge lifecycle"]
  node_ingestion["Knowledge ingestion<br/>[indexer.py]"]
  node_chunking["Document chunking<br/>[chunking.py]"]
  node_conversation_extract["Conversation extraction<br/>[conversations.py]"]
  node_privacy["Conversation privacy<br/>[privacy.py]"]
  node_knowledge_repo["Knowledge repository<br/>[repository.py]"]
  node_embeddings["Embedding client<br/>[embeddings.py]"]
  node_hybrid_store[("Hybrid search store<br/>[hybrid_store.py]")]
  node_vector_store[("Vector store<br/>[vector_store.py]")]
  node_retriever["FAQ retriever<br/>[retriever.py]"]
end

subgraph group_quality["Answer quality"]
  node_quality_runtime["Answer runtime<br/>[runtime.py]"]
  node_query["Query normalization<br/>[query.py]"]
  node_retrieval["Evidence retrieval<br/>[retrieval.py]"]
  node_generation["Answer generation<br/>[generation.py]"]
  node_ledger["Confidence ledger<br/>[ledger.py]"]
  node_quality_eval["Quality evaluation<br/>[evaluation.py]"]
end

subgraph group_state["Persistent state"]
  node_models[("Application records<br/>[models.py]")]
  node_session["Database sessions<br/>[session.py]"]
end

node_customer(("Customer"))
node_mysql[("MySQL")]
node_milvus[("Milvus")]
node_model_api["Model services"]

node_customer -->|"uses"| node_workbench
node_workbench -->|"streams chat"| node_http
node_http -->|"validates"| node_schemas
node_http -->|"dispatches chat"| node_chat
node_http -->|"dispatches extraction"| node_after_sale
node_chat -->|"builds answers"| node_quality_runtime
node_chat -->|"runs tools"| node_tools
node_tools -->|"invokes"| node_business
node_chat -->|"persists turns"| node_models
node_after_sale -.->|"extracts fields"| node_model_api
node_ingestion -->|"chunks documents"| node_chunking
node_ingestion -->|"writes chunks"| node_knowledge_repo
node_conversation_extract -->|"masks messages"| node_privacy
node_conversation_extract -->|"stages candidates"| node_knowledge_repo
node_knowledge_repo -->|"stores knowledge"| node_models
node_knowledge_repo -.->|"indexes pending"| node_embeddings
node_embeddings -->|"requests vectors"| node_model_api
node_embeddings -.->|"supplies vectors"| node_milvus
node_quality_runtime -->|"configures"| node_embeddings
node_quality_runtime -->|"configures"| node_hybrid_store
node_quality_runtime -->|"constructs"| node_retrieval
node_quality_runtime -->|"constructs"| node_generation
node_quality_runtime -->|"constructs"| node_ledger
node_retrieval -->|"normalizes"| node_query
node_retrieval -->|"embeds query"| node_embeddings
node_retrieval -->|"searches candidates"| node_hybrid_store
node_retrieval -->|"hydrates evidence"| node_models
node_generation -.->|"generates answer"| node_model_api
node_quality_runtime -->|"configures model"| node_model_api
node_quality_runtime -->|"configures reranker"| node_model_api
node_quality_eval -.->|"evaluates strategies"| node_quality_runtime
node_session -->|"opens sessions"| node_mysql
node_models -.->|"maps records"| node_mysql
node_retriever -->|"embeds query"| node_embeddings
node_retriever -->|"searches vectors"| node_vector_store
node_retriever -.->|"loads matches"| node_knowledge_repo
node_http -->|"initializes storage"| node_session
node_business -.->|"accesses business data"| node_models

click node_workbench "https://github.com/1012-penn/shophelperv2/blob/main/frontend/src/App.jsx"
click node_http "https://github.com/1012-penn/shophelperv2/blob/main/app/main.py"
click node_schemas "https://github.com/1012-penn/shophelperv2/blob/main/app/schemas.py"
click node_chat "https://github.com/1012-penn/shophelperv2/blob/main/app/services/chat.py"
click node_after_sale "https://github.com/1012-penn/shophelperv2/blob/main/app/services/after_sale.py"
click node_tools "https://github.com/1012-penn/shophelperv2/blob/main/app/tools/registry.py"
click node_business "https://github.com/1012-penn/shophelperv2/blob/main/app/tools/business.py"
click node_ingestion "https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/indexer.py"
click node_chunking "https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/chunking.py"
click node_conversation_extract "https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/conversations.py"
click node_privacy "https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/privacy.py"
click node_knowledge_repo "https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/repository.py"
click node_embeddings "https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/embeddings.py"
click node_hybrid_store "https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/hybrid_store.py"
click node_vector_store "https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/vector_store.py"
click node_retriever "https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/retriever.py"
click node_quality_runtime "https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/runtime.py"
click node_query "https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/query.py"
click node_retrieval "https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/retrieval.py"
click node_generation "https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/generation.py"
click node_ledger "https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/ledger.py"
click node_quality_eval "https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/evaluation.py"
click node_models "https://github.com/1012-penn/shophelperv2/blob/main/app/db/models.py"
click node_session "https://github.com/1012-penn/shophelperv2/blob/main/app/db/session.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_workbench,node_http,node_schemas toneBlue
class node_chat,node_after_sale,node_tools,node_business,node_mysql,node_milvus toneAmber
class node_ingestion,node_chunking,node_conversation_extract,node_privacy,node_knowledge_repo,node_embeddings,node_hybrid_store,node_vector_store,node_retriever toneMint
class node_quality_runtime,node_query,node_retrieval,node_generation,node_ledger,node_quality_eval toneRose
class node_models,node_session,node_customer,node_model_api toneIndigo
```

## Components

### Web and API

- [Support workbench](https://github.com/1012-penn/shophelperv2/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [HTTP application](https://github.com/1012-penn/shophelperv2/blob/main/app/main.py): `app/main.py`
- [Request schemas](https://github.com/1012-penn/shophelperv2/blob/main/app/schemas.py): `app/schemas.py`

### Support workflow

- [Chat orchestration](https://github.com/1012-penn/shophelperv2/blob/main/app/services/chat.py): `app/services/chat.py`
- [After-sale extraction](https://github.com/1012-penn/shophelperv2/blob/main/app/services/after_sale.py): `app/services/after_sale.py`
- [Business tools](https://github.com/1012-penn/shophelperv2/blob/main/app/tools/registry.py): `app/tools/registry.py`
- [Order operations](https://github.com/1012-penn/shophelperv2/blob/main/app/tools/business.py): `app/tools/business.py`

### Knowledge lifecycle

- [Knowledge ingestion](https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/indexer.py): `app/services/knowledge/indexer.py`
- [Document chunking](https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/chunking.py): `app/services/knowledge/chunking.py`
- [Conversation extraction](https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/conversations.py): `app/services/knowledge/conversations.py`
- [Conversation privacy](https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/privacy.py): `app/services/knowledge/privacy.py`
- [Knowledge repository](https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/repository.py): `app/services/knowledge/repository.py`
- [Embedding client](https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/embeddings.py): `app/services/knowledge/embeddings.py`
- [Hybrid search store](https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/hybrid_store.py): `app/services/knowledge/hybrid_store.py`
- [Vector store](https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/vector_store.py): `app/services/knowledge/vector_store.py`
- [FAQ retriever](https://github.com/1012-penn/shophelperv2/blob/main/app/services/knowledge/retriever.py): `app/services/knowledge/retriever.py`

### Answer quality

- [Answer runtime](https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/runtime.py): `app/services/quality/runtime.py`
- [Query normalization](https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/query.py): `app/services/quality/query.py`
- [Evidence retrieval](https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/retrieval.py): `app/services/quality/retrieval.py`
- [Answer generation](https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/generation.py): `app/services/quality/generation.py`
- [Confidence ledger](https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/ledger.py): `app/services/quality/ledger.py`
- [Quality evaluation](https://github.com/1012-penn/shophelperv2/blob/main/app/services/quality/evaluation.py): `app/services/quality/evaluation.py`

### Persistent state

- [Application records](https://github.com/1012-penn/shophelperv2/blob/main/app/db/models.py): `app/db/models.py`
- [Database sessions](https://github.com/1012-penn/shophelperv2/blob/main/app/db/session.py): `app/db/session.py`

### Other components

- **Customer**
- **MySQL**
- **Milvus**
- **Model services**

## Connections

- Customer → Support workbench: uses (evidence: `README.md`)
- Support workbench → HTTP application: streams chat (evidence: `README.md`)
- HTTP application → Request schemas: validates (evidence: `app/main.py`)
- HTTP application → Chat orchestration: dispatches chat (evidence: `app/main.py`)
- HTTP application → After-sale extraction: dispatches extraction (evidence: `app/main.py`)
- Chat orchestration → Answer runtime: builds answers (evidence: `app/services/quality/runtime.py`)
- Chat orchestration → Business tools: runs tools (evidence: `app/services/chat.py`)
- Business tools → Order operations: invokes (evidence: `app/services/chat.py`)
- Chat orchestration → Application records: persists turns (evidence: `app/services/chat.py`)
- After-sale extraction → Model services: extracts fields (evidence: `app/services/after_sale.py`)
- Knowledge ingestion → Document chunking: chunks documents (evidence: `app/services/knowledge/chunking.py`)
- Knowledge ingestion → Knowledge repository: writes chunks (evidence: `app/services/knowledge/indexer.py`)
- Conversation extraction → Conversation privacy: masks messages (evidence: `app/services/knowledge/conversations.py`)
- Conversation extraction → Knowledge repository: stages candidates (evidence: `app/services/knowledge/conversations.py`)
- Knowledge repository → Application records: stores knowledge (evidence: `app/services/knowledge/repository.py`)
- Knowledge repository → Embedding client: indexes pending
- Embedding client → Model services: requests vectors (evidence: `app/services/knowledge/embeddings.py`)
- Embedding client → Milvus: supplies vectors
- Answer runtime → Embedding client: configures (evidence: `app/services/quality/runtime.py`)
- Answer runtime → Hybrid search store: configures (evidence: `app/services/quality/runtime.py`)
- Answer runtime → Evidence retrieval: constructs (evidence: `app/services/quality/runtime.py`)
- Answer runtime → Answer generation: constructs (evidence: `app/services/quality/runtime.py`)
- Answer runtime → Confidence ledger: constructs (evidence: `app/services/quality/runtime.py`)
- Evidence retrieval → Query normalization: normalizes (evidence: `app/services/quality/retrieval.py`)
- Evidence retrieval → Embedding client: embeds query (evidence: `app/services/quality/retrieval.py`)
- Evidence retrieval → Hybrid search store: searches candidates (evidence: `app/services/quality/retrieval.py`)
- Evidence retrieval → Application records: hydrates evidence (evidence: `app/services/quality/retrieval.py`)
- Answer generation → Model services: generates answer
- Answer runtime → Model services: configures model (evidence: `app/services/quality/runtime.py`)
- Answer runtime → Model services: configures reranker (evidence: `app/services/quality/runtime.py`)
- Quality evaluation → Answer runtime: evaluates strategies
- Database sessions → MySQL: opens sessions (evidence: `app/db/session.py`)
- Application records → MySQL: maps records
- FAQ retriever → Embedding client: embeds query (evidence: `app/services/knowledge/retriever.py`)
- FAQ retriever → Vector store: searches vectors (evidence: `app/services/knowledge/retriever.py`)
- FAQ retriever → Knowledge repository: loads matches
- HTTP application → Database sessions: initializes storage (evidence: `app/main.py`)
- Order operations → Application records: accesses business data (evidence: `app/tools/business.py`)
