# wooseok-shin/hscode_identification architecture

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

## Overview

This repository is a research prototype for identifying Harmonized System codes from trade-item names. Its workflow cleans labeled product-name data, builds Word2Vec-based inputs, trains a classifier for either two- or four-digit codes, and predicts ranked classes for new names; the README describes expanding predictions to six digits by cosine similarity. The six scripts combine these stages rather than calling a shared training pipeline, and import helpers from modules.py. The excerpts show preprocessing, model construction and prediction, but not the full training or similarity-expansion implementation.

Main entry points: [`modules.py`](https://github.com/wooseok-shin/hscode_identification/blob/master/modules.py) (Cleaning and metrics), [`CNN_2digits.py`](https://github.com/wooseok-shin/hscode_identification/blob/master/CNN_2digits.py) (CNN 2-digit), [`CNN_4digits.py`](https://github.com/wooseok-shin/hscode_identification/blob/master/CNN_4digits.py) (CNN 4-digit), [`FCN_2digits.py`](https://github.com/wooseok-shin/hscode_identification/blob/master/FCN_2digits.py) (FCN 2-digit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_preparation["Shared preparation"]
  node_helpers["Cleaning and metrics<br/>[modules.py]"]
end

subgraph group_cnn["CNN classifiers"]
  node_cnn2["CNN 2-digit<br/>[CNN_2digits.py]"]
  node_cnn4["CNN 4-digit<br/>[CNN_4digits.py]"]
end

subgraph group_fcn["FCN classifiers"]
  node_fcn2["FCN 2-digit<br/>[FCN_2digits.py]"]
  node_fcn4["FCN 4-digit<br/>[FCN_4digits.py]"]
end

subgraph group_lstm["LSTM classifiers"]
  node_lstm2["LSTM 2-digit<br/>[LSTM_2digits.py]"]
  node_lstm4["LSTM 4-digit<br/>[LSTM_4digits.py]"]
end

node_user(("Trade user"))
node_labeled_data["Labeled names"]
node_ranked_codes["Ranked code predictions"]
node_six_digit["Six-digit expansion"]

node_user -.->|"runs prediction"| node_cnn2
node_user -.->|"runs prediction"| node_cnn4
node_user -.->|"runs prediction"| node_fcn2
node_user -.->|"runs prediction"| node_fcn4
node_user -.->|"runs prediction"| node_lstm2
node_user -.->|"runs prediction"| node_lstm4
node_labeled_data -->|"reads labels"| node_cnn2
node_labeled_data -->|"reads labels"| node_cnn4
node_labeled_data -->|"reads labels"| node_fcn2
node_labeled_data -->|"reads labels"| node_fcn4
node_labeled_data -->|"reads labels"| node_lstm2
node_labeled_data -->|"reads labels"| node_lstm4
node_cnn2 -->|"imports helpers"| node_helpers
node_cnn4 -->|"imports helpers"| node_helpers
node_fcn2 -->|"imports helpers"| node_helpers
node_fcn4 -->|"imports helpers"| node_helpers
node_lstm2 -->|"imports helpers"| node_helpers
node_lstm4 -->|"imports helpers"| node_helpers
node_cnn2 -->|"prints predictions"| node_ranked_codes
node_cnn4 -->|"prints predictions"| node_ranked_codes
node_fcn2 -->|"prints predictions"| node_ranked_codes
node_fcn4 -->|"prints predictions"| node_ranked_codes
node_lstm2 -->|"prints predictions"| node_ranked_codes
node_lstm4 -->|"prints predictions"| node_ranked_codes
node_ranked_codes -.->|"expands by similarity"| node_six_digit

click node_helpers "https://github.com/wooseok-shin/hscode_identification/blob/master/modules.py"
click node_cnn2 "https://github.com/wooseok-shin/hscode_identification/blob/master/CNN_2digits.py"
click node_cnn4 "https://github.com/wooseok-shin/hscode_identification/blob/master/CNN_4digits.py"
click node_fcn2 "https://github.com/wooseok-shin/hscode_identification/blob/master/FCN_2digits.py"
click node_fcn4 "https://github.com/wooseok-shin/hscode_identification/blob/master/FCN_4digits.py"
click node_lstm2 "https://github.com/wooseok-shin/hscode_identification/blob/master/LSTM_2digits.py"
click node_lstm4 "https://github.com/wooseok-shin/hscode_identification/blob/master/LSTM_4digits.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_helpers,node_user toneBlue
class node_cnn2,node_cnn4 toneAmber
class node_fcn2,node_fcn4 toneMint
class node_lstm2,node_lstm4 toneRose
class node_labeled_data,node_ranked_codes,node_six_digit toneIndigo
```

## Components

### Shared preparation

- [Cleaning and metrics](https://github.com/wooseok-shin/hscode_identification/blob/master/modules.py): `modules.py`

### CNN classifiers

- [CNN 2-digit](https://github.com/wooseok-shin/hscode_identification/blob/master/CNN_2digits.py): `CNN_2digits.py`
- [CNN 4-digit](https://github.com/wooseok-shin/hscode_identification/blob/master/CNN_4digits.py): `CNN_4digits.py`

### FCN classifiers

- [FCN 2-digit](https://github.com/wooseok-shin/hscode_identification/blob/master/FCN_2digits.py): `FCN_2digits.py`
- [FCN 4-digit](https://github.com/wooseok-shin/hscode_identification/blob/master/FCN_4digits.py): `FCN_4digits.py`

### LSTM classifiers

- [LSTM 2-digit](https://github.com/wooseok-shin/hscode_identification/blob/master/LSTM_2digits.py): `LSTM_2digits.py`
- [LSTM 4-digit](https://github.com/wooseok-shin/hscode_identification/blob/master/LSTM_4digits.py): `LSTM_4digits.py`

### Other components

- **Trade user**
- **Labeled names**
- **Ranked code predictions**
- **Six-digit expansion**

## Connections

- Trade user → CNN 2-digit: runs prediction (evidence: `README.md`)
- Trade user → CNN 4-digit: runs prediction (evidence: `README.md`)
- Trade user → FCN 2-digit: runs prediction (evidence: `README.md`)
- Trade user → FCN 4-digit: runs prediction (evidence: `README.md`)
- Trade user → LSTM 2-digit: runs prediction (evidence: `README.md`)
- Trade user → LSTM 4-digit: runs prediction (evidence: `README.md`)
- Labeled names → CNN 2-digit: reads labels (evidence: `CNN_2digits.py`)
- Labeled names → CNN 4-digit: reads labels (evidence: `CNN_4digits.py`)
- Labeled names → FCN 2-digit: reads labels (evidence: `FCN_2digits.py`)
- Labeled names → FCN 4-digit: reads labels (evidence: `FCN_4digits.py`)
- Labeled names → LSTM 2-digit: reads labels (evidence: `LSTM_2digits.py`)
- Labeled names → LSTM 4-digit: reads labels (evidence: `LSTM_4digits.py`)
- CNN 2-digit → Cleaning and metrics: imports helpers (evidence: `CNN_2digits.py`)
- CNN 4-digit → Cleaning and metrics: imports helpers (evidence: `CNN_4digits.py`)
- FCN 2-digit → Cleaning and metrics: imports helpers (evidence: `FCN_2digits.py`)
- FCN 4-digit → Cleaning and metrics: imports helpers (evidence: `FCN_4digits.py`)
- LSTM 2-digit → Cleaning and metrics: imports helpers (evidence: `LSTM_2digits.py`)
- LSTM 4-digit → Cleaning and metrics: imports helpers (evidence: `LSTM_4digits.py`)
- CNN 2-digit → Ranked code predictions: prints predictions (evidence: `CNN_2digits.py`)
- CNN 4-digit → Ranked code predictions: prints predictions (evidence: `CNN_4digits.py`)
- FCN 2-digit → Ranked code predictions: prints predictions (evidence: `FCN_2digits.py`)
- FCN 4-digit → Ranked code predictions: prints predictions (evidence: `FCN_4digits.py`)
- LSTM 2-digit → Ranked code predictions: prints predictions (evidence: `LSTM_2digits.py`)
- LSTM 4-digit → Ranked code predictions: prints predictions (evidence: `LSTM_4digits.py`)
- Ranked code predictions → Six-digit expansion: expands by similarity (evidence: `README.md`)