Shipmate

Shipmate is an international trade compliance assistant that analyzes shipment details and provides a comprehensive report covering required documents, regulatory requirements, duties, packaging standards, and risk assessments. It is powered by the Google Gemini API.

The project is split into two parts: a React frontend built with Vite, and a Python backend built with FastAPI.

You will need two separate terminal windows—one for the frontend and one for the backend.

The backend handles the API routing and interacts with the Google Gemini API.

Navigate to the backend directory:

cd backend

Set up your Python environment:

1. Create a virtual environment (optional but recommended):

   python -m venv .venv

2. Activate the virtual environment:
   • Windows: .\.venv\Scripts\activate
   • macOS/Linux: source .venv/bin/activate
3. Install the required dependencies:

   pip install -r requirements.txt

Configure Environment Variables:

1. Create a .env file in the backend directory (you can use .env.example as a reference):

   copy .env.example .env

2. Open the .env file and add your Google Gemini API key:

   GEMINI_API_KEY=your_gemini_api_key_here

Start the backend server:

python main.py

The API will start running locally at http://localhost:8000.

The frontend provides the user interface for entering shipment details and viewing the generated compliance reports.

Navigate to the frontend directory:

cd frontend

Install dependencies:

npm install

Configure Environment Variables (Optional): By default, the frontend will assume your backend is running at http://localhost:8000. If you need to change this, you can create a .env file in the frontend directory:

1. copy .env.example .env
2. Update the variable inside:

   VITE_API_URL=http://localhost:8000

Start the frontend development server:

npm run dev

The app will open automatically in your browser (usually at http://localhost:5173).

• Frontend: React, Vite
• Backend: Python, FastAPI, Uvicorn, httpx
• AI: Google Gemini API (gemini-2.5-flash)