# ghaly26/precious-metals-dashboard architecture

> Architecture diagram of the GitHub repository ghaly26/precious-metals-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ghaly26/precious-metals-dashboard
- Repository: https://github.com/ghaly26/precious-metals-dashboard
- Video tour (about a minute): https://gitdiagram.com/ghaly26/precious-metals-dashboard/video

## Overview

Queen Jewelry’s portal turns metal, purity, weight, and fee inputs into valuation quotes or invoices. The React app also supports client verification, address confirmation, PDF generation, quote notifications, and invoice shipping labels; the Express service supplies market data and handles verification, notification, and USPS operations. The README documents purity-scaled gold/silver pricing and the ounce/gram matrix. Source excerpts are partial, so uncertain endpoint wiring is omitted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/ghaly26/precious-metals-dashboard/blob/main/frontend/src/App.jsx) (Portal and calculators), [`backend/src/server.js`](https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js) (Spot-price service), [`frontend/src/main.jsx`](https://github.com/ghaly26/precious-metals-dashboard/blob/main/frontend/src/main.jsx) (React entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Valuation interface"]
  node_app["Portal and calculators<br/>[App.jsx]"]
  node_entry["React entry point<br/>[main.jsx]"]
  node_estimator["Melt estimator<br/>[App.jsx]"]
  node_pdf["Quote and invoice PDF<br/>[App.jsx]"]
end

subgraph group_pricing["Market pricing"]
  node_market["Spot-price service<br/>[server.js]"]
  node_cache[("Price cache<br/>[server.js]")]
  node_purity["Purity and price matrix<br/>[server.js]"]
end

subgraph group_transactions["Client transactions"]
  node_api["Express API<br/>[server.js]"]
  node_verification["Invoice verification<br/>[server.js]"]
  node_address["Address confirmation<br/>[server.js]"]
  node_quote["Quote notifications<br/>[server.js]"]
  node_shipping["Shipping label creation<br/>[server.js]"]
  node_quota["Quota reminders<br/>[server.js]"]
end

subgraph group_integrations["External integrations"]
  node_golddev["goldprice.dev"]
  node_metalsdev["metals.dev"]
  node_resend["Resend email"]
  node_usps["USPS services"]
  node_ipapi["IP geolocation"]
end

node_customer(("Jewelry evaluator"))

node_entry -->|"renders"| node_app
node_customer -->|"enters inputs"| node_app
node_app -->|"fetches prices"| node_api
node_api -->|"requests prices"| node_market
node_market -->|"reads or writes"| node_cache
node_market -.->|"queries XAU/XAG"| node_golddev
node_market -.->|"queries XAU/XAG"| node_metalsdev
node_market -->|"builds price payload"| node_purity
node_api -->|"returns prices"| node_app
node_app -->|"calculates valuation"| node_estimator
node_app -->|"requests code"| node_verification
node_app -->|"verifies address"| node_address
node_app -->|"generates document"| node_pdf
node_app -->|"sends quote data"| node_quote
node_quote -->|"sends email"| node_resend
node_verification -->|"sends code"| node_resend
node_app -->|"requests label"| node_shipping
node_shipping -->|"requests label"| node_usps
node_address -->|"checks address"| node_usps
node_quota -.->|"checks usage"| node_golddev
node_quota -->|"sends reminder"| node_resend
node_api -->|"schedules checks"| node_quota
node_api -.->|"looks up IP"| node_ipapi

click node_app "https://github.com/ghaly26/precious-metals-dashboard/blob/main/frontend/src/App.jsx"
click node_entry "https://github.com/ghaly26/precious-metals-dashboard/blob/main/frontend/src/main.jsx"
click node_api "https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js"
click node_market "https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js"
click node_cache "https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js"
click node_purity "https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js"
click node_estimator "https://github.com/ghaly26/precious-metals-dashboard/blob/main/frontend/src/App.jsx"
click node_verification "https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js"
click node_address "https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js"
click node_quote "https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js"
click node_pdf "https://github.com/ghaly26/precious-metals-dashboard/blob/main/frontend/src/App.jsx"
click node_shipping "https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js"
click node_quota "https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js"

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_app,node_entry,node_estimator,node_pdf toneBlue
class node_market,node_cache,node_purity toneAmber
class node_api,node_verification,node_address,node_quote,node_shipping,node_quota toneMint
class node_golddev,node_metalsdev,node_resend,node_usps,node_ipapi toneRose
class node_customer toneIndigo
```

## Components

### Valuation interface

- [Portal and calculators](https://github.com/ghaly26/precious-metals-dashboard/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [React entry point](https://github.com/ghaly26/precious-metals-dashboard/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Melt estimator](https://github.com/ghaly26/precious-metals-dashboard/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Quote and invoice PDF](https://github.com/ghaly26/precious-metals-dashboard/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Market pricing

- [Spot-price service](https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js): `backend/src/server.js`
- [Price cache](https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js): `backend/src/server.js`
- [Purity and price matrix](https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js): `backend/src/server.js`

### Client transactions

- [Express API](https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js): `backend/src/server.js`
- [Invoice verification](https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js): `backend/src/server.js`
- [Address confirmation](https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js): `backend/src/server.js`
- [Quote notifications](https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js): `backend/src/server.js`
- [Shipping label creation](https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js): `backend/src/server.js`
- [Quota reminders](https://github.com/ghaly26/precious-metals-dashboard/blob/main/backend/src/server.js): `backend/src/server.js`

### External integrations

- **goldprice.dev**
- **metals.dev**
- **Resend email**
- **USPS services**
- **IP geolocation**

### Other components

- **Jewelry evaluator**

## Connections

- React entry point → Portal and calculators: renders
- Jewelry evaluator → Portal and calculators: enters inputs
- Portal and calculators → Express API: fetches prices
- Express API → Spot-price service: requests prices
- Spot-price service → Price cache: reads or writes
- Spot-price service → goldprice.dev: queries XAU/XAG
- Spot-price service → metals.dev: queries XAU/XAG
- Spot-price service → Purity and price matrix: builds price payload
- Express API → Portal and calculators: returns prices
- Portal and calculators → Melt estimator: calculates valuation
- Portal and calculators → Invoice verification: requests code
- Portal and calculators → Address confirmation: verifies address
- Portal and calculators → Quote and invoice PDF: generates document
- Portal and calculators → Quote notifications: sends quote data
- Quote notifications → Resend email: sends email
- Invoice verification → Resend email: sends code
- Portal and calculators → Shipping label creation: requests label
- Shipping label creation → USPS services: requests label
- Address confirmation → USPS services: checks address
- Quota reminders → goldprice.dev: checks usage
- Quota reminders → Resend email: sends reminder
- Express API → Quota reminders: schedules checks
- Express API → IP geolocation: looks up IP