# ihsanandrinal/hs-code-search-engine architecture

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

- Interactive diagram: https://gitdiagram.com/ihsanandrinal/hs-code-search-engine
- Repository: https://github.com/ihsanandrinal/hs-code-search-engine

## Overview

This is a React HS-code commodity search app backed by Algolia, with a Node/Express API that can search the index and request Claude tariff analysis. The main user flow is browser search and facet filtering against Algolia, followed by optional per-result analysis through the Heroku API. CSV indexing is a separate data-preparation path. The repository contains two near-identical backend/indexer pairs; the excerpts show their behavior, but not which deployment is active beyond the frontend’s explicit Heroku analysis URL.

Main entry points: [`client/src/App.jsx`](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/client/src/App.jsx) (Search and results UI), [`heroku-backend/server.js`](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/heroku-backend/server.js) (Heroku API), [`server/server.js`](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/server/server.js) (Server API), [`heroku-backend/index_data.js`](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/heroku-backend/index_data.js) (Heroku indexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Search interface"]
  node_app["Search and results UI<br/>[App.jsx]"]
  node_entry["React entry point<br/>[index.js]"]
end

subgraph group_api["Backend APIs"]
  node_heroku_api["Heroku API<br/>[server.js]"]
  node_server_api["Server API<br/>[server.js]"]
end

subgraph group_data["Index preparation"]
  node_heroku_csv["Heroku CSV data<br/>[hs_codes.csv]"]
  node_heroku_indexer["Heroku indexer<br/>[index_data.js]"]
  node_server_csv["Server CSV data<br/>[hs_codes.csv]"]
  node_server_indexer["Server indexer<br/>[index_data.js]"]
end

node_user(("Trade user"))
node_algolia[("HS-code index")]
node_claude["Claude API"]

node_user -->|"opens app"| node_entry
node_entry -->|"renders"| node_app
node_user -->|"searches and filters"| node_app
node_app -->|"searches index"| node_algolia
node_algolia -->|"returns hits"| node_app
node_app -->|"requests analysis"| node_heroku_api
node_heroku_api -->|"requests analysis"| node_claude
node_claude -->|"returns analysis"| node_heroku_api
node_heroku_api -->|"returns analysis"| node_app
node_heroku_api -->|"searches index"| node_algolia
node_heroku_indexer -->|"reads rows"| node_heroku_csv
node_heroku_indexer -->|"clears and indexes"| node_algolia
node_server_api -->|"searches index"| node_algolia
node_server_api -->|"requests analysis"| node_claude
node_claude -->|"returns analysis"| node_server_api
node_server_indexer -->|"reads rows"| node_server_csv
node_server_indexer -->|"clears and indexes"| node_algolia

click node_app "https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/client/src/App.jsx"
click node_entry "https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/client/src/index.js"
click node_heroku_api "https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/heroku-backend/server.js"
click node_server_api "https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/server/server.js"
click node_heroku_csv "https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/heroku-backend/hs_codes.csv"
click node_heroku_indexer "https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/heroku-backend/index_data.js"
click node_server_csv "https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/server/hs_codes.csv"
click node_server_indexer "https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/server/index_data.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_user toneBlue
class node_heroku_api,node_server_api,node_algolia toneAmber
class node_heroku_csv,node_heroku_indexer,node_server_csv,node_server_indexer,node_claude toneMint
```

## Components

### Search interface

- [Search and results UI](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [React entry point](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/client/src/index.js): `client/src/index.js`

### Backend APIs

- [Heroku API](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/heroku-backend/server.js): `heroku-backend/server.js`
- [Server API](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/server/server.js): `server/server.js`

### Index preparation

- [Heroku CSV data](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/heroku-backend/hs_codes.csv): `heroku-backend/hs_codes.csv`
- [Heroku indexer](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/heroku-backend/index_data.js): `heroku-backend/index_data.js`
- [Server CSV data](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/server/hs_codes.csv): `server/hs_codes.csv`
- [Server indexer](https://github.com/ihsanandrinal/hs-code-search-engine/blob/main/server/index_data.js): `server/index_data.js`

### Other components

- **Trade user**
- **HS-code index**
- **Claude API**

## Connections

- Trade user → React entry point: opens app (evidence: `client/src/index.js`)
- React entry point → Search and results UI: renders (evidence: `client/src/index.js`)
- Trade user → Search and results UI: searches and filters (evidence: `client/src/App.jsx`)
- Search and results UI → HS-code index: searches index (evidence: `client/src/App.jsx`)
- HS-code index → Search and results UI: returns hits (evidence: `client/src/App.jsx`)
- Search and results UI → Heroku API: requests analysis (evidence: `client/src/App.jsx`)
- Heroku API → Claude API: requests analysis (evidence: `heroku-backend/server.js`)
- Claude API → Heroku API: returns analysis (evidence: `heroku-backend/server.js`)
- Heroku API → Search and results UI: returns analysis (evidence: `client/src/App.jsx`)
- Heroku API → HS-code index: searches index (evidence: `heroku-backend/server.js`)
- Heroku indexer → Heroku CSV data: reads rows (evidence: `heroku-backend/index_data.js`)
- Heroku indexer → HS-code index: clears and indexes (evidence: `heroku-backend/index_data.js`)
- Server API → HS-code index: searches index (evidence: `server/server.js`)
- Server API → Claude API: requests analysis (evidence: `server/server.js`)
- Claude API → Server API: returns analysis (evidence: `server/server.js`)
- Server indexer → Server CSV data: reads rows (evidence: `server/index_data.js`)
- Server indexer → HS-code index: clears and indexes (evidence: `server/index_data.js`)