# haochibao/hackharvard2025 architecture

> Architecture diagram of the GitHub repository haochibao/hackharvard2025, 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/haochibao/hackharvard2025
- Repository: https://github.com/haochibao/hackharvard2025

## Overview

This repository combines a browser extension that collects checkout-session, interaction, and location signals with a merchant-facing fraud-analysis API. The API workflow is merchant request → authentication and fraud analysis → in-memory transaction storage, with high-risk analyses optionally sent to a merchant webhook. Merchant registration, email verification, dashboard reporting, and SDK access are separate capabilities. The extension excerpts show tracking and browser-storage behavior, but not its wiring to the API; that connection is therefore omitted. Several API routes and extension modules were not sampled in full.

Main entry points: [`api/server.js`](https://github.com/haochibao/hackharvard2025/blob/main/api/server.js) (HTTP Server), [`api/storage/localStorage.js`](https://github.com/haochibao/hackharvard2025/blob/main/api/storage/localStorage.js) (In-Memory Store), [`api/routes/fraud.js`](https://github.com/haochibao/hackharvard2025/blob/main/api/routes/fraud.js) (Fraud Routes), [`api/middleware/auth.js`](https://github.com/haochibao/hackharvard2025/blob/main/api/middleware/auth.js) (Merchant Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Browser Extension"]
  node_extension_content["Checkout Tracking<br/>[app.js]"]
  node_extension_content_entry["Content Script<br/>[content.js]"]
  node_extension_modal["Session Modal<br/>[modal.js]"]
  node_extension_popup["Extension Popup<br/>[popup.js]"]
  node_extension_background["Background Worker<br/>[background.js]"]
  node_extension_background_functions["Background Functions<br/>[functions.js]"]
end

subgraph group_api["Fraud API"]
  node_api_server["HTTP Server<br/>[server.js]"]
  node_fraud_routes["Fraud Routes<br/>[fraud.js]"]
  node_fraud_detector["Risk Analysis<br/>[fraudDetector.js]"]
  node_auth["Merchant Authentication<br/>[auth.js]"]
end

subgraph group_merchant["Merchant Services"]
  node_merchant_routes["Merchant Accounts<br/>[merchants.js]"]
  node_email_routes["Email Verification"]
  node_dashboard_routes["Dashboard Reporting<br/>[dashboard.js]"]
  node_webhook_routes["Webhook Management<br/>[webhooks.js]"]
  node_fraud_sdk["Fraud SDK"]
end

subgraph group_state["Runtime State"]
  node_storage_index["Storage Facade<br/>[index.js]"]
  node_memory_store[("In-Memory Store<br/>[localStorage.js]")]
end

node_browser_user(("Shopper"))
node_merchant_client(("Merchant Client"))
node_merchant_webhook(("Merchant Webhook"))

node_browser_user -.->|"interacts with"| node_extension_content
node_extension_content -.->|"requests location"| node_extension_background
node_merchant_client -.->|"sends requests"| node_api_server
node_api_server -->|"mounts routes"| node_fraud_routes
node_api_server -->|"mounts routes"| node_merchant_routes
node_api_server -->|"mounts routes"| node_email_routes
node_api_server -->|"mounts routes"| node_dashboard_routes
node_api_server -->|"mounts routes"| node_webhook_routes
node_fraud_routes -->|"authenticates with"| node_auth
node_fraud_routes -->|"analyzes transactions"| node_fraud_detector
node_fraud_routes -->|"reads and writes"| node_memory_store
node_fraud_routes -->|"posts high-risk analysis"| node_merchant_webhook
node_auth -->|"looks up API key"| node_memory_store
node_auth -->|"imports shared maps"| node_storage_index
node_merchant_routes -->|"manages merchant data"| node_memory_store
node_email_routes -->|"stores verification codes"| node_memory_store
node_dashboard_routes -->|"reads reporting data"| node_memory_store
node_storage_index -->|"exports shared store"| node_memory_store

click node_extension_content "https://github.com/haochibao/hackharvard2025/blob/main/extension/app/content/app.js"
click node_extension_content_entry "https://github.com/haochibao/hackharvard2025/blob/main/extension/app/content/content.js"
click node_extension_modal "https://github.com/haochibao/hackharvard2025/blob/main/extension/app/content/modal.js"
click node_extension_popup "https://github.com/haochibao/hackharvard2025/blob/main/extension/app/popup/popup.js"
click node_extension_background "https://github.com/haochibao/hackharvard2025/blob/main/extension/background/background.js"
click node_extension_background_functions "https://github.com/haochibao/hackharvard2025/blob/main/extension/background/functions.js"
click node_api_server "https://github.com/haochibao/hackharvard2025/blob/main/api/server.js"
click node_fraud_routes "https://github.com/haochibao/hackharvard2025/blob/main/api/routes/fraud.js"
click node_fraud_detector "https://github.com/haochibao/hackharvard2025/blob/main/api/services/fraudDetector.js"
click node_merchant_routes "https://github.com/haochibao/hackharvard2025/blob/main/api/routes/merchants.js"
click node_email_routes "https://github.com/haochibao/hackharvard2025/blob/main/api/routes/email-verification.js"
click node_dashboard_routes "https://github.com/haochibao/hackharvard2025/blob/main/api/routes/dashboard.js"
click node_webhook_routes "https://github.com/haochibao/hackharvard2025/blob/main/api/routes/webhooks.js"
click node_fraud_sdk "https://github.com/haochibao/hackharvard2025/blob/main/api/sdk/fraud-detection-sdk.js"
click node_auth "https://github.com/haochibao/hackharvard2025/blob/main/api/middleware/auth.js"
click node_storage_index "https://github.com/haochibao/hackharvard2025/blob/main/api/storage/index.js"
click node_memory_store "https://github.com/haochibao/hackharvard2025/blob/main/api/storage/localStorage.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_extension_content,node_extension_content_entry,node_extension_modal,node_extension_popup,node_extension_background,node_extension_background_functions,node_merchant_client toneBlue
class node_api_server,node_fraud_routes,node_fraud_detector,node_auth toneAmber
class node_merchant_routes,node_email_routes,node_dashboard_routes,node_webhook_routes,node_fraud_sdk,node_merchant_webhook toneMint
class node_storage_index,node_memory_store toneRose
class node_browser_user toneIndigo
```

## Components

### Browser Extension

- [Checkout Tracking](https://github.com/haochibao/hackharvard2025/blob/main/extension/app/content/app.js): `extension/app/content/app.js`
- [Content Script](https://github.com/haochibao/hackharvard2025/blob/main/extension/app/content/content.js): `extension/app/content/content.js`
- [Session Modal](https://github.com/haochibao/hackharvard2025/blob/main/extension/app/content/modal.js): `extension/app/content/modal.js`
- [Extension Popup](https://github.com/haochibao/hackharvard2025/blob/main/extension/app/popup/popup.js): `extension/app/popup/popup.js`
- [Background Worker](https://github.com/haochibao/hackharvard2025/blob/main/extension/background/background.js): `extension/background/background.js`
- [Background Functions](https://github.com/haochibao/hackharvard2025/blob/main/extension/background/functions.js): `extension/background/functions.js`

### Fraud API

- [HTTP Server](https://github.com/haochibao/hackharvard2025/blob/main/api/server.js): `api/server.js`
- [Fraud Routes](https://github.com/haochibao/hackharvard2025/blob/main/api/routes/fraud.js): `api/routes/fraud.js`
- [Risk Analysis](https://github.com/haochibao/hackharvard2025/blob/main/api/services/fraudDetector.js): `api/services/fraudDetector.js`
- [Merchant Authentication](https://github.com/haochibao/hackharvard2025/blob/main/api/middleware/auth.js): `api/middleware/auth.js`

### Merchant Services

- [Merchant Accounts](https://github.com/haochibao/hackharvard2025/blob/main/api/routes/merchants.js): `api/routes/merchants.js`
- [Email Verification](https://github.com/haochibao/hackharvard2025/blob/main/api/routes/email-verification.js): `api/routes/email-verification.js`
- [Dashboard Reporting](https://github.com/haochibao/hackharvard2025/blob/main/api/routes/dashboard.js): `api/routes/dashboard.js`
- [Webhook Management](https://github.com/haochibao/hackharvard2025/blob/main/api/routes/webhooks.js): `api/routes/webhooks.js`
- [Fraud SDK](https://github.com/haochibao/hackharvard2025/blob/main/api/sdk/fraud-detection-sdk.js): `api/sdk/fraud-detection-sdk.js`

### Runtime State

- [Storage Facade](https://github.com/haochibao/hackharvard2025/blob/main/api/storage/index.js): `api/storage/index.js`
- [In-Memory Store](https://github.com/haochibao/hackharvard2025/blob/main/api/storage/localStorage.js): `api/storage/localStorage.js`

### Other components

- **Shopper**
- **Merchant Client**
- **Merchant Webhook**

## Connections

- Shopper → Checkout Tracking: interacts with
- Checkout Tracking → Background Worker: requests location
- Merchant Client → HTTP Server: sends requests
- HTTP Server → Fraud Routes: mounts routes (evidence: `api/server.js`)
- HTTP Server → Merchant Accounts: mounts routes (evidence: `api/server.js`)
- HTTP Server → Email Verification: mounts routes (evidence: `api/server.js`)
- HTTP Server → Dashboard Reporting: mounts routes (evidence: `api/server.js`)
- HTTP Server → Webhook Management: mounts routes (evidence: `api/server.js`)
- Fraud Routes → Merchant Authentication: authenticates with (evidence: `api/routes/fraud.js`)
- Fraud Routes → Risk Analysis: analyzes transactions (evidence: `api/routes/fraud.js`)
- Fraud Routes → In-Memory Store: reads and writes (evidence: `api/routes/fraud.js`)
- Fraud Routes → Merchant Webhook: posts high-risk analysis (evidence: `api/routes/fraud.js`)
- Merchant Authentication → In-Memory Store: looks up API key (evidence: `api/middleware/auth.js`)
- Merchant Authentication → Storage Facade: imports shared maps (evidence: `api/middleware/auth.js`)
- Merchant Accounts → In-Memory Store: manages merchant data (evidence: `api/routes/merchants.js`)
- Email Verification → In-Memory Store: stores verification codes (evidence: `api/routes/email-verification.js`)
- Dashboard Reporting → In-Memory Store: reads reporting data (evidence: `api/routes/dashboard.js`)
- Storage Facade → In-Memory Store: exports shared store (evidence: `api/storage/index.js`)
