SafeShipping - 06/16/2025 06:16AM

SafeShipping is a blockchain-based logistics platform using smart contracts, decentralized oracles, and IoT integrations to automate, secure, and verify global shipping workflows.

Project Structure

This repository contains a comprehensive directory structure for developing and deploying the SafeShipping platform. For detailed information about the directory structure, please refer to the directory_structure.md file.

Key Components

• Smart Contracts: Blockchain contracts for secure, transparent shipping workflows
• WASM Assembly Language: Web Assembly Language for performance and efficiency
• Backend API: Server-side application for business logic and data management
• Frontend Application: User interface for interacting with the platform
• IoT Integration: Components for connecting with IoT devices and sensors
• Oracle Services: Decentralized data feeds connecting smart contracts with external data
• Documentation: Comprehensive guides for developers and users

Getting Started

1. Clone this repository
2. Review the directory structure documentation
3. Set up the development environment using Docker
4. Begin implementing components based on the provided structure

🧱 Backend Setup (WSL + Docker Compose)

✅ You launched backend services via:

bash bash ./docker/build/dev_compose.sh

This script was previously docker-compose_local_only.sh, now reorganized into docker/build/.

✅ Backend containers included:

backend-api for manifest intake

oracle-service for token minting

blockchain-node for ledger simulation

✅ You confirmed the manifest POST route worked with:

bash curl -X POST http://localhost:8080/api/intake/manifest
-H "Content-Type: application/json"
-d '{"sender":"Richard", "receiver":"Kalani", "carrier":"FedEx"}'

🖥️ Frontend Setup (Local Vite Dev)

✅ You ran:

bash cd frontend npm run dev Which launched the Vite dev server at http://localhost:5173.

---

🚀 Startup Modes

Choose your environment:

• Local
• Dev Stack
• Production

---

🧑‍💻 Local Startup

For manual development without containers.

🔹 Backend (WSL Ubuntu)

wsl -d Ubuntu
cd ~/Projects/SafeShipping/backend
uvicorn src.main:app --host 0.0.0.0 --port=8080 --reload
Or launch via Docker Compose:

bash
bash docker/build/dev_compose.sh
🔹 Frontend (Windows Host)
bash
cd frontend
npm install
npm run dev
Access the UI at: http://localhost:5173

🧪 Dev Startup (Full Stack via Docker)
Runs all containers with dev tooling and hot reload.

🔹 Services
backend-api
oracle-service
blockchain-node
frontend
smart-contracts

🔹 Launch All
bash
cd docker
bash ./build/dev_compose.sh
Compose file used: docker/config/docker-compose.yml

Verify containers:

bash
docker ps
🏭 Production Deployment
🔹 Docker Compose (Secure Build)
Use production compose file:

bash
docker compose -f docker/config/docker-compose.prod.yml up -d
Includes HTTPS, env injection, and production images.

🔹 Kubernetes (Optional)
If using K8s, apply manifests from:

k8s/
├── deployment.yaml
├── service.yaml
├── ingress.yaml

bash
kubectl apply -f k8s/
📋 Manifest Workflow (Manual Test)
🔹 Submit Manifest via Curl

bash test CORS
curl -i -X OPTIONS http://localhost:3000/shipment \
  -H "Origin: http://localhost:5173" \
  -H "Access-Control-Request-Method: POST"

HTTP/1.1 204 No Content
X-Powered-By: Express
Access-Control-Allow-Origin: http://localhost:5173
Vary: Origin, Access-Control-Request-Headers
Access-Control-Allow-Methods: GET,HEAD,PUT,PATCH,POST,DELETE
Content-Length: 0
Date: Fri, 12 Sep 2025 19:48:22 GMT
Connection: keep-alive
Keep-Alive: timeout=5


bash test CORS
curl -i -X OPTIONS http://localhost:8080/api/intake/manifest \
  -H "Origin: http://localhost:5173" \
  -H "Access-Control-Request-Method: POST"

HTTP/1.1 204 No Content
X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,HEAD,PUT,PATCH,POST,DELETE
Vary: Access-Control-Request-Headers
Content-Length: 0
Date: Fri, 12 Sep 2025 19:48:50 GMT
Connection: keep-alive
Keep-Alive: timeout=5

bash test MANIFEST
curl -i -X POST http://localhost:3000/shipment \
  -H "Origin: http://localhost:5173" \
  -H "Content-Type: application/json" \
  -d `{
    "action": "submit",
    "agent": { "carrier": "FedEx" },
    "shipment": {
      "id": "MOCK-001",
      "origin": "Denver, CO",
      "destination": "San Diego, CA",
      "contents": ["Books", "Electronics"],
      "timestamp": "2025-09-12T18:30:00Z"
    }`

HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: http://localhost:5173
Vary: Origin
Content-Type: application/json; charset=utf-8
Content-Length: 192
ETag: W/"c0-eUZOuRKqSOB3yxXBd+JYHxlLezw"
Date: Fri, 12 Sep 2025 19:51:52 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"status":"success","carrier":"FedEx","token":"mock-token-1z4ljwmf","blockchain_tx":"0xf4fd4fd088e53000000000000000000000000000000000000000000000000000","timestamp":"2025-09-12T19:51:52.475Z"}

🔹 Submit via Frontend Button
Fill out the form

Click "Submit via API"

Paste Manafest for Submission

Example Manafest
---
{
  "carrier": "FedEx",
  "origin": "Denver, CO",
  "destination": "San Diego, CA",
  "weight": "15lbs",
  "dimensions": "18x12x10",
  "insurance": true,
  "transportMode": "air",
  "priority": "Express",
  "sender": "Acme Corp",
  "receiver": "John Doe",
  "contents": ["Books", "Electronics", "Clothing"],
  "fragility": "High",
  "departure_location": "Denver International Airport",
  "departure_time": "2025-09-15T09:00:00Z",
  "status_dispatch": "Dispatched",
  "contract_hash": "0xabc123def456...",
  "status_transit": "In Transit",
  "customs_clearance": "Cleared",
  "arrival_location": "San Diego International Airport",
  "arrival_time": "2025-09-16T14:30:00Z",
  "status_delivery": "Pending",
  "notes": "Handle with care – fragile items"
}

---

Token will display on successful response

POST /audit hit — received: {
  source: 'manual',
  role: 'agent',
  timestamp: '2025-10-10T16:36:14.298Z',
  action: 'submitOrder'
}
DEBUG: Returning stubbed blockchain response: {
  status: 'success',
  carrier: 'FedEx',
  token: 'mock-live-token-mi7qv8i5',
  blockchain_tx: '0xad0f7d35160b9000000000000000000000000000000000000000000000000000',
  timestamp: '2025-10-10T16:36:14.871Z',
  contract_id: 'demo-contract-377'
}
POST /audit hit — received: {
  source: 'manual',
  role: 'agent',
  timestamp: '2025-10-10T16:36:21.862Z',
  action: 'submitOrder'
}
DEBUG: Returning stubbed blockchain response: {
  status: 'success',
  carrier: 'FedEx',
  token: 'mock-live-token-0bs9zrfc',
  blockchain_tx: '0x18983e2edfab4000000000000000000000000000000000000000000000000000',
  timestamp: '2025-10-10T16:36:22.389Z',
  contract_id: 'demo-contract-840'
}

-----------------------------------------------------------------------------------------

⚙️ Folder Structure Summary
SAFESHIPPING/
├── backend/               # API logic, token minting
├── frontend/              # Vite UI
├── docker/
│   ├── build/             # Shell scripts for builds
│   ├── test/              # Shell scripts for testing
│   ├── dev/               # Dev launchers
│   ├── config/            # Compose YAMLs
│   └── frontend/          # Dockerfile.dev for UI
├── k8s/                   # Kubernetes manifests
├── scripts/               # Blockchain test utils (curl)
├── .env                   # Runtime env vars
├── .env.example           # Template env vars
├── cleanup_root.sh        # Root cleanup utility
├── README.md              # You are here


🧠 Tips for Developers
🟢 Always run backend before frontend if doing local dev

🔄 Use cleanup_root.sh after major file restructuring

📦 Manifest tokens are logged and traceable on-chain

🛡️ Write tests inside tests/ and run with pytest or npm test

👥 Contributors
Name	Role
Richard	Lead Architect & Token Designer
Richard	UX Systems & Compliance Logic



## License

This project is licensed under the GPL-3.0 License - see the [LICENSE](./LICENSE) file for details.