# rkv762/dhaga-next-purchase-nudge architecture

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

- Interactive diagram: https://gitdiagram.com/rkv762/dhaga-next-purchase-nudge
- Repository: https://github.com/rkv762/dhaga-next-purchase-nudge

## Overview

Dhaga & Co.’s Next Purchase Nudge turns customer orders, browsing, returns and reviews into a grounded product recommendation and re-engagement message, with evaluation and human-review outcomes. The main workflow runs through the API or local demo into a pipeline that fetches history, profiles and routes the customer, checks safety and ranks products, verifies SKUs, then drafts and evaluates a message. Supporting capabilities include configurable model selection, reviewer decisions, cost tracking and a browser UI. Some stage links rely on README documentation because source excerpts are partial.

Main entry points: [`src/pipeline.py`](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/pipeline.py) (Pipeline runner), [`src/data_access.py`](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/data_access.py) (CSV data access), [`app.py`](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/app.py) (FastAPI API), [`src/schemas.py`](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/schemas.py) (Model and result schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_web_ui["Web demo<br/>[index.html]"]
  node_api["FastAPI API<br/>[app.py]"]
  node_local_demo["Local demo CLI<br/>[demo.py]"]
end

subgraph group_orchestration["Pipeline orchestration"]
  node_pipeline["Pipeline runner<br/>[pipeline.py]"]
  node_schemas["Model and result schemas<br/>[schemas.py]"]
  node_settings["Run settings<br/>[settings.py]"]
end

subgraph group_recommendation["Recommendation stages"]
  node_profile["Profile extraction<br/>[chains.py]"]
  node_persona["Persona routing<br/>[chains.py]"]
  node_safety["Persona safety check<br/>[chains.py]"]
  node_shortlist["SKU shortlist<br/>[chains.py]"]
  node_grounding["SKU grounding<br/>[data_access.py]"]
  node_message["Message drafting<br/>[chains.py]"]
  node_evaluation["Message evaluation<br/>[chains.py]"]
  node_chains["Model chains<br/>[chains.py]"]
end

subgraph group_data_governance["Data and governance"]
  node_data_access["CSV data access<br/>[data_access.py]"]
  node_sample_data["Synthetic customer data"]
  node_decision_log["Decision log<br/>[data_access.py]"]
  node_review["Review decisions<br/>[review.py]"]
  node_pricing["Model cost estimates<br/>[pricing.py]"]
end

subgraph group_services["Model services"]
  node_model_provider["Anthropic or OpenRouter"]
end

node_customer(("Customer or operator"))
node_human_reviewer(("Human reviewer"))

node_customer -->|"uses"| node_web_ui
node_web_ui -->|"calls API"| node_api
node_customer -->|"runs"| node_local_demo
node_local_demo -->|"runs"| node_pipeline
node_api -->|"runs"| node_pipeline
node_api -->|"lists customers"| node_data_access
node_api -->|"configures run"| node_settings
node_api -->|"submits decision"| node_review
node_human_reviewer -.->|"reviews result"| node_web_ui
node_human_reviewer -->|"submits review"| node_api
node_pipeline -->|"fetches history"| node_data_access
node_pipeline -->|"extracts profile"| node_profile
node_pipeline -->|"routes persona"| node_persona
node_pipeline -->|"checks safety"| node_safety
node_pipeline -->|"ranks candidates"| node_shortlist
node_pipeline -->|"gets candidates"| node_data_access
node_pipeline -->|"verifies SKUs"| node_grounding
node_pipeline -->|"drafts message"| node_message
node_pipeline -->|"evaluates draft"| node_evaluation
node_pipeline -->|"uses settings"| node_settings
node_profile -->|"returns profile"| node_schemas
node_persona -->|"returns decision"| node_schemas
node_safety -->|"returns check"| node_schemas
node_shortlist -->|"returns picks"| node_schemas
node_message -->|"returns draft"| node_schemas
node_evaluation -->|"returns score"| node_schemas
node_data_access -->|"reads CSVs"| node_sample_data
node_review -->|"validates customer"| node_data_access
node_review -->|"records decision"| node_data_access
node_pipeline -->|"logs outcome"| node_data_access
node_chains -.->|"calls model"| node_model_provider
node_pricing -.->|"prices usage"| node_model_provider

click node_web_ui "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/index.html"
click node_api "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/app.py"
click node_local_demo "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/scripts/demo.py"
click node_pipeline "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/pipeline.py"
click node_profile "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py"
click node_persona "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py"
click node_safety "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py"
click node_shortlist "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py"
click node_grounding "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/data_access.py"
click node_message "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py"
click node_evaluation "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py"
click node_schemas "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/schemas.py"
click node_settings "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/settings.py"
click node_data_access "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/data_access.py"
click node_sample_data "https://github.com/rkv762/dhaga-next-purchase-nudge/tree/main/data"
click node_decision_log "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/data_access.py"
click node_review "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/review.py"
click node_pricing "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/pricing.py"
click node_chains "https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.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_web_ui,node_api,node_local_demo,node_human_reviewer toneBlue
class node_pipeline,node_schemas,node_settings toneAmber
class node_profile,node_persona,node_safety,node_shortlist,node_grounding,node_message,node_evaluation,node_chains toneMint
class node_data_access,node_sample_data,node_decision_log,node_review,node_pricing toneRose
class node_model_provider,node_customer toneIndigo
```

## Components

### User entry points

- [Web demo](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/index.html): `index.html`
- [FastAPI API](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/app.py): `app.py`
- [Local demo CLI](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/scripts/demo.py): `scripts/demo.py`

### Pipeline orchestration

- [Pipeline runner](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/pipeline.py): `src/pipeline.py`
- [Model and result schemas](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/schemas.py): `src/schemas.py`
- [Run settings](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/settings.py): `src/settings.py`

### Recommendation stages

- [Profile extraction](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py): `src/chains.py`
- [Persona routing](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py): `src/chains.py`
- [Persona safety check](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py): `src/chains.py`
- [SKU shortlist](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py): `src/chains.py`
- [SKU grounding](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/data_access.py): `src/data_access.py`
- [Message drafting](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py): `src/chains.py`
- [Message evaluation](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py): `src/chains.py`
- [Model chains](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/chains.py): `src/chains.py`

### Data and governance

- [CSV data access](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/data_access.py): `src/data_access.py`
- [Synthetic customer data](https://github.com/rkv762/dhaga-next-purchase-nudge/tree/main/data): `data`
- [Decision log](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/data_access.py): `src/data_access.py`
- [Review decisions](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/review.py): `src/review.py`
- [Model cost estimates](https://github.com/rkv762/dhaga-next-purchase-nudge/blob/main/src/pricing.py): `src/pricing.py`

### Model services

- **Anthropic or OpenRouter**

### Other components

- **Customer or operator**
- **Human reviewer**

## Connections

- Customer or operator → Web demo: uses (evidence: `README.md`)
- Web demo → FastAPI API: calls API (evidence: `README.md`)
- Customer or operator → Local demo CLI: runs (evidence: `README.md`)
- Local demo CLI → Pipeline runner: runs (evidence: `scripts/demo.py`)
- FastAPI API → Pipeline runner: runs (evidence: `app.py`)
- FastAPI API → CSV data access: lists customers (evidence: `app.py`)
- FastAPI API → Run settings: configures run (evidence: `app.py`)
- FastAPI API → Review decisions: submits decision (evidence: `app.py`)
- Human reviewer → Web demo: reviews result
- Human reviewer → FastAPI API: submits review (evidence: `app.py`)
- Pipeline runner → CSV data access: fetches history (evidence: `src/pipeline.py`)
- Pipeline runner → Profile extraction: extracts profile (evidence: `src/pipeline.py`)
- Pipeline runner → Persona routing: routes persona (evidence: `README.md`)
- Pipeline runner → Persona safety check: checks safety (evidence: `src/pipeline.py`)
- Pipeline runner → SKU shortlist: ranks candidates (evidence: `src/pipeline.py`)
- Pipeline runner → CSV data access: gets candidates (evidence: `src/pipeline.py`)
- Pipeline runner → SKU grounding: verifies SKUs (evidence: `src/pipeline.py`)
- Pipeline runner → Message drafting: drafts message (evidence: `src/pipeline.py`)
- Pipeline runner → Message evaluation: evaluates draft (evidence: `src/pipeline.py`)
- Pipeline runner → Run settings: uses settings (evidence: `src/pipeline.py`)
- Profile extraction → Model and result schemas: returns profile (evidence: `src/chains.py`)
- Persona routing → Model and result schemas: returns decision (evidence: `src/chains.py`)
- Persona safety check → Model and result schemas: returns check (evidence: `src/chains.py`)
- SKU shortlist → Model and result schemas: returns picks (evidence: `src/chains.py`)
- Message drafting → Model and result schemas: returns draft (evidence: `src/chains.py`)
- Message evaluation → Model and result schemas: returns score (evidence: `src/chains.py`)
- CSV data access → Synthetic customer data: reads CSVs (evidence: `src/data_access.py`)
- Review decisions → CSV data access: validates customer (evidence: `src/review.py`)
- Review decisions → CSV data access: records decision (evidence: `src/review.py`)
- Pipeline runner → CSV data access: logs outcome (evidence: `src/pipeline.py`)
- Model chains → Anthropic or OpenRouter: calls model
- Model cost estimates → Anthropic or OpenRouter: prices usage
