# tensortorch777/hypevault architecture

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

- Interactive diagram: https://gitdiagram.com/tensortorch777/hypevault
- Repository: https://github.com/tensortorch777/hypevault

## Overview

HypeVault is a luxury-watch listings marketplace whose central workflow screens seller photos before publication: size, AI provenance/copy, watch content, model verdict and possible proof-photo hold, followed by admin review. Separate capabilities identify watches from photos or text, compare prices from live eBay and dated Chrono24/dealer data, and offer gated research inference and explanations. The graph follows documented and indexed calls; some UI-to-API links and unsampled subsystem internals are left unverified rather than inferred.

Main entry points: [`frontend/src/app/api/upstream/[...path]/route.ts`](https://github.com/tensortorch777/hypevault/blob/main/frontend/src/app/api/upstream/%5B...path%5D/route.ts) (API Proxy), [`backend/inference/routes.py`](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/routes.py) (Screening Endpoint), [`backend/listings/routes.py`](https://github.com/tensortorch777/hypevault/blob/main/backend/listings/routes.py) (Listing Routes), [`backend/market/service.py`](https://github.com/tensortorch777/hypevault/blob/main/backend/market/service.py) (Market Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Marketplace UI"]
  node_upload["Photo Upload<br/>[page.tsx]"]
  node_webproxy["API Proxy<br/>[route.ts]"]
  node_reviewui["Review Queue UI<br/>[ReviewQueue.tsx]"]
  node_marketui["Market UI<br/>[page.tsx]"]
  node_researchui["Research UI<br/>[page.tsx]"]
end

subgraph group_screen["Listing Screening"]
  node_listingroutes["Listing Routes<br/>[routes.py]"]
  node_screenroutes["Screening Endpoint<br/>[routes.py]"]
  node_screening["Screening Decisions<br/>[screening.py]"]
  node_provenance["Signed AI Labels<br/>[provenance.py]"]
  node_knownai["Known AI Copies<br/>[known_ai.py]"]
  node_content["Watch Content Gate<br/>[content_gate.py]"]
  node_live["Live Model Screening<br/>[live_screening.py]"]
  node_engine["Inference Backend<br/>[engine.py]"]
  node_triton["Triton Client<br/>[triton_client.py]"]
end

subgraph group_market["Identification &amp; Market"]
  node_marketroutes["Market Routes<br/>[routes.py]"]
  node_identify["Watch Identification<br/>[service.py]"]
  node_recognize["Recognition Engine<br/>[recognize.py]"]
  node_marketservice["Market Search<br/>[service.py]"]
  node_marketrepo["Market Repository<br/>[repository.py]"]
  node_ebay["eBay Browse<br/>[ebay_browse.py]"]
  node_dealers["Dealer Sources<br/>[service.py]"]
end

subgraph group_platform["Accounts &amp; Persistence"]
  node_storage["Photo Storage<br/>[storage.py]"]
  node_db[("PostgreSQL Models<br/>[database.py]")]
  node_auth["Authentication<br/>[routes.py]"]
end

subgraph group_research["Research Inference"]
  node_researchroutes["Research Routes<br/>[research_routes.py]"]
  node_router["Model Router<br/>[model_router.py]"]
  node_occlusion["Occlusion Explanations<br/>[occlusion.py]"]
  node_researchaccess["Research Access<br/>[research_access.py]"]
end

node_seller(("Seller"))
node_admin(("Admin Reviewer"))

node_seller -.->|"submits photo"| node_upload
node_upload -.->|"sends request"| node_webproxy
node_webproxy -.->|"forwards API"| node_screenroutes
node_screenroutes -->|"runs checks"| node_screening
node_screenroutes -->|"gets model verdict"| node_live
node_screenroutes -->|"checks credentials"| node_provenance
node_screenroutes -->|"checks copies"| node_knownai
node_screenroutes -->|"checks watch content"| node_content
node_screening -->|"uses label check"| node_provenance
node_screening -->|"uses content check"| node_content
node_live -->|"uses inference backend"| node_engine
node_engine -->|"dispatches inference"| node_triton
node_listingroutes -->|"screens listing"| node_screening
node_listingroutes -->|"gets model result"| node_live
node_listingroutes -->|"checks rejected copies"| node_knownai
node_listingroutes -->|"stores photo"| node_storage
node_listingroutes -->|"reads and writes listings"| node_db
node_admin -.->|"reviews held items"| node_reviewui
node_reviewui -.->|"requests review data"| node_webproxy
node_marketui -.->|"requests market data"| node_webproxy
node_webproxy -.->|"forwards API"| node_marketroutes
node_marketroutes -->|"searches prices"| node_marketservice
node_marketroutes -->|"identifies watch"| node_identify
node_identify -->|"delegates recognition"| node_recognize
node_marketservice -->|"queries dataset"| node_marketrepo
node_marketservice -->|"searches live listings"| node_ebay
node_marketservice -->|"queries dealer data"| node_dealers
node_marketservice -->|"reads market data"| node_db
node_researchui -.->|"requests analysis"| node_webproxy
node_webproxy -.->|"forwards API"| node_researchroutes
node_researchroutes -->|"routes model inference"| node_router
node_researchroutes -->|"requests explanations"| node_occlusion
node_researchroutes -->|"checks access"| node_researchaccess
node_researchroutes -->|"reads research state"| node_db
node_auth -->|"reads account data"| node_db
node_auth -.->|"authenticates user"| node_seller

click node_upload "https://github.com/tensortorch777/hypevault/blob/main/frontend/src/app/seller/upload/page.tsx"
click node_webproxy "https://github.com/tensortorch777/hypevault/blob/main/frontend/src/app/api/upstream/%5B...path%5D/route.ts"
click node_reviewui "https://github.com/tensortorch777/hypevault/blob/main/frontend/src/components/admin/ReviewQueue.tsx"
click node_listingroutes "https://github.com/tensortorch777/hypevault/blob/main/backend/listings/routes.py"
click node_screenroutes "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/routes.py"
click node_screening "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/screening.py"
click node_provenance "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/provenance.py"
click node_knownai "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/known_ai.py"
click node_content "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/content_gate.py"
click node_live "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/live_screening.py"
click node_engine "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/engine.py"
click node_triton "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/triton_client.py"
click node_storage "https://github.com/tensortorch777/hypevault/blob/main/backend/storage.py"
click node_db "https://github.com/tensortorch777/hypevault/blob/main/backend/database.py"
click node_auth "https://github.com/tensortorch777/hypevault/blob/main/backend/auth/routes.py"
click node_marketui "https://github.com/tensortorch777/hypevault/blob/main/frontend/src/app/market/page.tsx"
click node_marketroutes "https://github.com/tensortorch777/hypevault/blob/main/backend/market/routes.py"
click node_identify "https://github.com/tensortorch777/hypevault/blob/main/backend/identify/service.py"
click node_recognize "https://github.com/tensortorch777/hypevault/blob/main/backend/identify/recognize.py"
click node_marketservice "https://github.com/tensortorch777/hypevault/blob/main/backend/market/service.py"
click node_marketrepo "https://github.com/tensortorch777/hypevault/blob/main/backend/market/repository.py"
click node_ebay "https://github.com/tensortorch777/hypevault/blob/main/backend/market/ebay_browse.py"
click node_dealers "https://github.com/tensortorch777/hypevault/blob/main/backend/market/dealers/service.py"
click node_researchui "https://github.com/tensortorch777/hypevault/blob/main/frontend/src/app/research/page.tsx"
click node_researchroutes "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/research_routes.py"
click node_router "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/model_router.py"
click node_occlusion "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/occlusion.py"
click node_researchaccess "https://github.com/tensortorch777/hypevault/blob/main/backend/inference/research_access.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_upload,node_webproxy,node_reviewui,node_marketui,node_researchui,node_admin toneBlue
class node_listingroutes,node_screenroutes,node_screening,node_provenance,node_knownai,node_content,node_live,node_engine,node_triton toneAmber
class node_marketroutes,node_identify,node_recognize,node_marketservice,node_marketrepo,node_ebay,node_dealers toneMint
class node_storage,node_db,node_auth toneRose
class node_researchroutes,node_router,node_occlusion,node_researchaccess,node_seller toneIndigo
```

## Components

### Marketplace UI

- [Photo Upload](https://github.com/tensortorch777/hypevault/blob/main/frontend/src/app/seller/upload/page.tsx): `frontend/src/app/seller/upload/page.tsx`
- [API Proxy](https://github.com/tensortorch777/hypevault/blob/main/frontend/src/app/api/upstream/%5B...path%5D/route.ts): `frontend/src/app/api/upstream/[...path]/route.ts`
- [Review Queue UI](https://github.com/tensortorch777/hypevault/blob/main/frontend/src/components/admin/ReviewQueue.tsx): `frontend/src/components/admin/ReviewQueue.tsx`
- [Market UI](https://github.com/tensortorch777/hypevault/blob/main/frontend/src/app/market/page.tsx): `frontend/src/app/market/page.tsx`
- [Research UI](https://github.com/tensortorch777/hypevault/blob/main/frontend/src/app/research/page.tsx): `frontend/src/app/research/page.tsx`

### Listing Screening

- [Listing Routes](https://github.com/tensortorch777/hypevault/blob/main/backend/listings/routes.py): `backend/listings/routes.py`
- [Screening Endpoint](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/routes.py): `backend/inference/routes.py`
- [Screening Decisions](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/screening.py): `backend/inference/screening.py`
- [Signed AI Labels](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/provenance.py): `backend/inference/provenance.py`
- [Known AI Copies](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/known_ai.py): `backend/inference/known_ai.py`
- [Watch Content Gate](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/content_gate.py): `backend/inference/content_gate.py`
- [Live Model Screening](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/live_screening.py): `backend/inference/live_screening.py`
- [Inference Backend](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/engine.py): `backend/inference/engine.py`
- [Triton Client](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/triton_client.py): `backend/inference/triton_client.py`

### Identification & Market

- [Market Routes](https://github.com/tensortorch777/hypevault/blob/main/backend/market/routes.py): `backend/market/routes.py`
- [Watch Identification](https://github.com/tensortorch777/hypevault/blob/main/backend/identify/service.py): `backend/identify/service.py`
- [Recognition Engine](https://github.com/tensortorch777/hypevault/blob/main/backend/identify/recognize.py): `backend/identify/recognize.py`
- [Market Search](https://github.com/tensortorch777/hypevault/blob/main/backend/market/service.py): `backend/market/service.py`
- [Market Repository](https://github.com/tensortorch777/hypevault/blob/main/backend/market/repository.py): `backend/market/repository.py`
- [eBay Browse](https://github.com/tensortorch777/hypevault/blob/main/backend/market/ebay_browse.py): `backend/market/ebay_browse.py`
- [Dealer Sources](https://github.com/tensortorch777/hypevault/blob/main/backend/market/dealers/service.py): `backend/market/dealers/service.py`

### Accounts & Persistence

- [Photo Storage](https://github.com/tensortorch777/hypevault/blob/main/backend/storage.py): `backend/storage.py`
- [PostgreSQL Models](https://github.com/tensortorch777/hypevault/blob/main/backend/database.py): `backend/database.py`
- [Authentication](https://github.com/tensortorch777/hypevault/blob/main/backend/auth/routes.py): `backend/auth/routes.py`

### Research Inference

- [Research Routes](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/research_routes.py): `backend/inference/research_routes.py`
- [Model Router](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/model_router.py): `backend/inference/model_router.py`
- [Occlusion Explanations](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/occlusion.py): `backend/inference/occlusion.py`
- [Research Access](https://github.com/tensortorch777/hypevault/blob/main/backend/inference/research_access.py): `backend/inference/research_access.py`

### Other components

- **Seller**
- **Admin Reviewer**

## Connections

- Seller → Photo Upload: submits photo
- Photo Upload → API Proxy: sends request
- API Proxy → Screening Endpoint: forwards API
- Screening Endpoint → Screening Decisions: runs checks (evidence: `backend/inference/routes.py`)
- Screening Endpoint → Live Model Screening: gets model verdict (evidence: `backend/inference/routes.py`)
- Screening Endpoint → Signed AI Labels: checks credentials (evidence: `backend/inference/routes.py`)
- Screening Endpoint → Known AI Copies: checks copies (evidence: `backend/inference/routes.py`)
- Screening Endpoint → Watch Content Gate: checks watch content (evidence: `backend/inference/routes.py`)
- Screening Decisions → Signed AI Labels: uses label check (evidence: `backend/inference/screening.py`)
- Screening Decisions → Watch Content Gate: uses content check (evidence: `backend/inference/screening.py`)
- Live Model Screening → Inference Backend: uses inference backend (evidence: `backend/inference/live_screening.py`)
- Inference Backend → Triton Client: dispatches inference (evidence: `backend/inference/engine.py`)
- Listing Routes → Screening Decisions: screens listing (evidence: `backend/listings/routes.py`)
- Listing Routes → Live Model Screening: gets model result (evidence: `backend/listings/routes.py`)
- Listing Routes → Known AI Copies: checks rejected copies (evidence: `backend/listings/routes.py`)
- Listing Routes → Photo Storage: stores photo (evidence: `backend/listings/routes.py`)
- Listing Routes → PostgreSQL Models: reads and writes listings (evidence: `backend/listings/routes.py`)
- Admin Reviewer → Review Queue UI: reviews held items
- Review Queue UI → API Proxy: requests review data
- Market UI → API Proxy: requests market data
- API Proxy → Market Routes: forwards API
- Market Routes → Market Search: searches prices (evidence: `backend/market/routes.py`)
- Market Routes → Watch Identification: identifies watch (evidence: `backend/market/routes.py`)
- Watch Identification → Recognition Engine: delegates recognition (evidence: `backend/identify/service.py`)
- Market Search → Market Repository: queries dataset (evidence: `backend/market/service.py`)
- Market Search → eBay Browse: searches live listings (evidence: `backend/market/service.py`)
- Market Search → Dealer Sources: queries dealer data (evidence: `backend/market/service.py`)
- Market Search → PostgreSQL Models: reads market data
- Research UI → API Proxy: requests analysis
- API Proxy → Research Routes: forwards API
- Research Routes → Model Router: routes model inference (evidence: `backend/inference/research_routes.py`)
- Research Routes → Occlusion Explanations: requests explanations (evidence: `backend/inference/research_routes.py`)
- Research Routes → Research Access: checks access (evidence: `backend/inference/research_routes.py`)
- Research Routes → PostgreSQL Models: reads research state (evidence: `backend/inference/research_routes.py`)
- Authentication → PostgreSQL Models: reads account data (evidence: `backend/auth/routes.py`)
- Authentication → Seller: authenticates user
