Skip to content

TheJinius/CS203-Project

BranchesTags

Repository files navigation

Static Badge

Trade Optimization Pathfinder (TOP)

An all-in-one Tariff Management Platform to streamline the process of calculating tariffs and optimizing trade routes between countries.

Watch the video

🌍 Problem Statement

Design and implement a system called TARIFF (Trade Agreements Regulating Imports and Foreign Fees):
Its purpose is to define import tariffs (and/or additional fees) and calculate them across industries or products between different countries at any given time.

💡 Our Solution

Trade Optimization Pathfinder (TOP) simplifies and unifies the Tariff Calculation and Management process by providing:

  • 🧮 Accurate trade route tariff calculations
  • 🧑‍💼 Admin management tools for tariffs
  • 🌐 Interactive route visualization for smarter coordination

🎯 Features

Baseline Tariff Calculation Process

image

Step 1: Enter source and destination countries to search for goods using HSCode or descriptions
image

Step 2: System returns available tariff(s). Select from dropdown and enter product quantity
Step 3: Choose desired currency conversion and calculate the result

💱 Exchange Rate Conversion

Exchange rates are pulled hourly from ExchangeRateAPI and cached in Redis, ensuring both speed and accuracy without straining API limits.

🧩 Explainable Calculation

TOP transparently breaks down the formula and displays each step:

  • Builds user trust in the final calculation
  • Helps learners understand tariff computation mechanics

✅ Compliance Checklist

image

Provides users with post-calculation compliance requirements such as declarations and certifications.
Built using Pinecone + OpenAI for semantic search with JSON-structured results for the frontend.
All items are sourced from official government reports with direct source links for verification.

🗺️ Route Visualization

image

Displays four optimized route types:

  • ⚠️ Risk – lowest likelihood of incidents and piracy for shipping
  • 💸 Cost – cheapest route
  • 🌿 Carbon – eco-friendly route
  • ⏱️ Time – fastest shipping option

Each route includes a breakdown across all four factors for deeper comparison.

🤖 AI Chatbot

image

Our chatbot uses a Retrieval-Augmented Generation (RAG) system:

  1. User sends a query
  2. Pinecone retrieves relevant tariff data
  3. GPT generates a data-grounded, source-backed answer

This ensures accuracy and reliability — not hallucination.

image

Admins can upload or update tariff documents directly in Pinecone.

📊 Results Tab

Quickly build new routes, compare tariffs, and export results as a PDF report.

🧭 Multi-Leg Route Builder

image

Combine multiple legs across various countries to optimize cost and efficiency.
Compare direct vs. multi-leg routes seamlessly.

⚖️ Tariff Comparator

image

Compare tariffs based on the following factors:

  • Risk
  • Cost
  • Carbon emissions
  • Time

With additional analytics:
image

🔒 Security

image

Secured via AWS Cognito with strict least-privilege access control.

User Type Permissions
User Access tariff calculations, results tab, chatbot
Admin All user features + Tariff Management and Chatbot Data Editing

⚙️ Tariff Management (Admin)

Admin-only page for:

  • ➕ Add/Delete Tariff – stay up-to-date with changing regulations
  • ✏️ Edit Tariff – correct mistakes without database rebuilds
  • 📚 Update Chatbot Context – manage compliance documents used in RAG system

🛠️ Technical Implementation

  • Frontend: React + TypeScript (Mapbox for visualization)
  • Backend: Java (Spring Boot), Python
  • Databases: PostgreSQL, Neo4J, Pinecone, Redis
  • Deployment: Vercel (Frontend), AWS EC2 (Backend)

🔁 CI/CD Pipeline Overview

ci-cd

Automated via GitHub Actions:

  1. Runs full test suite
  2. Deploys backend to AWS EC2
  3. Deploys frontend to Vercel

Ensures production stays synchronized with every main branch push.

🧮 Database & Pipelines

er-diagram pipeline

Automated background pipelines:

  • 🗓️ Monthly: Tariff data ingestion
  • ⏱️ Hourly: Exchange rate updates

Powered by AWS Lambda, Redis, and DynamoDB.

🚀 Running the Project Locally

The .env.local file at frontend/.env.local is already configured to use the local endpoints. Simply perform the local setups shown below.

Note that for ease of use, there is a deployed cloud instance of the graph database hosted on Neo4j, which local endpoints reference. The provided .env file at graphdb/.env already points to the cloud database, hence no action is needed. However, it is on a free trial, and will expire on 28th November 2025. Past this date, the deployed frontend will no longer display the various trade routes, though other features will work as intended. To see the trade route visualisation after the trial expires, you must run all endpoints locally.

Backend Setup

mvn install
mvn spring-boot:run

This runs locally at http://localhost:8080/.

Frontend Setup

cd frontend
npm install
npm run dev

This runs locally at http://localhost:3000/.

Chatbot Setup (in Bash)

cd "Python RAG chatbot"
python -m venv .venv
source .venv/Scripts/activate
pip install -r requirements.txt
uvicorn src.api_server:app --reload --host 0.0.0.0 --port 8000

This runs locally at http://localhost:8000.

Replace source .venv/Scripts/activate with:

  • .\.venv\Scripts\Activate.ps1 when running from PowerShell, or
  • .\.venv\Scripts\activate.bat when running from Command Prompt

Compliance Checklist Setup (in Bash)

cd Compliance_checklist
python -m venv .venv
source .venv/Scripts/activate
pip install -r requirements.txt
uvicorn src.api_server:app --reload --host 0.0.0.0 --port 8001

This runs locally at http://localhost:8001.

Replace source .venv/Scripts/activate with:

  • .\.venv\Scripts\Activate.ps1 when running from PowerShell, or
  • .\.venv\Scripts\activate.bat when running from Command Prompt

Graph Database API (in Bash)

cd graphdb
python -m venv .venv
source .venv/Scripts/activate
pip install -r requirements.txt
py main.py

Replace source .venv/Scripts/activate with:

  • .\.venv\Scripts\Activate.ps1 when running from PowerShell, or
  • .\.venv\Scripts\activate.bat when running from Command Prompt

This runs locally at http://localhost:8002.

Graph Database Cloud Instance

  1. Install Neo4j desktop. Follow the installation instructions.
  2. Create a new database instance. Note down the database user and the password. Ensure the values of the NEO4J_USER and NEO4J_PASSWORD environment variables in graphdb/.env are respectively updated to these values.
  3. Enable the Graph Data Science (GDS) and APOC plugins by clicking on menu (3 dots) -> Plugins -> Install Graph Data Science and APOC plugins
  4. Delete the pre-existing generatedneo4j database, if any. Then, stop the database instance, and load the .dump file by clicking "Load database from file" and selecting the neo4j.dump file provided at graphdb/neo4j.dump.
  5. Start the instance again, if it did not automatically start running in step 4. It will be running on localhost, port 7687. You should also see the connection URI (e.g. neo4j://127.0.0.1:7687 - check the exact URI you are provided). Delete the NEO4J_URI variable in the provided .env file at graphdb/.env and replace it with this value.

🧪 Running Tests

mvn clean test
mvn test -Dtest=TariffManagementControllerIntegrationTest
mvn jacoco:report

🌐 Deployed Servers

Service URL
Frontend https://trade-optimisation-pathfinder.vercel.app
Backend https://cs203tariffproject.duckdns.org
Chatbot https://cs203chatbot.duckdns.org
Compliance Checklist https://cs203compliance.duckdns.org

Note: If you encounter a NetworkError while on SMU Wi-Fi, switch to another network (DNS blocking issue).

🧱 Backend Testing Requirements

Ensure Docker Desktop is running before executing tests:

docker ps
mvn test

If Docker is not running, integration tests will fail.

Team

This project was built by

About

cs-203-project.vercel.app

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages