GSCX Platform — Technical Documentation

GSCXNodeJS/
├── src/
│   ├── server.js            Express entry point, static serving, /api mount
│   ├── db.js                MariaDB pool, query() helper
│   ├── routes/
│   │   └── api.js           All REST endpoints (~2 400 lines)
│   ├── services/
│   │   ├── compliance.js    Compliance flag checking + middleware
│   │   ├── paymentOrchestrator.js  Route scoring
│   │   ├── paymentRails.js  Rail normalisation + validation
│   │   ├── reconciliation.js  Ledger reconciliation engine
│   │   └── moochedda.js     MooChedda API wrapper (crypto payments)
│   └── sql/
│       └── schema.sql       CREATE TABLE + idempotent ALTER migrations
├── public/
│   ├── index.html           SPA shell
│   ├── app.js               Full frontend (~4 600 lines)
│   └── styles.css           CSS custom-property theming
├── Docs.html                This file
└── SystemOverview.html      Executive overview

Data Model — Members

members

Central identity table. Every other entity references this via foreign key.

Data Model — Products

products

Marketplace listings created by Exporters. Supports trade classification fields.

Data Model — Trade Orders & Shipments

import_orders

Full customs-grade import declaration. Covers IOR identity, HS classification, regulatory flags (FDA/FCC/USDA), payment terms, and duty responsibilities.

export_profiles

One-per-exporter legal entity profile: registration number, tax ID, beneficial owners. Required before creating shipments.

export_shipments

Individual export consignment. Tracks ECCN, dual-use flag, port of loading, export licence, and customs clearance status.

beneficiaries & remittances

A Remitter defines beneficiaries (bank, crypto, or internal recipients) and then submits remittances against them. Remittances are compliance-gated via requireCompliance middleware — any BLOCK-severity flag on the member blocks submission with HTTP 403.

payout_accounts

Member-owned receiving accounts (bank or crypto) used for export proceeds and refunds.

Data Model — Transport

transport_shipments

Carrier-level shipment record. Links to an export or import order. Stores AWB, BOL, manifest URL, origin/destination addresses, cargo weight/volume, customs status, and proof-of-delivery fields (recipient name, signature URL, photo URL).

shipment_events

Event log per shipment: LABEL_CREATED → PICKED_UP → IN_TRANSIT → AT_CUSTOMS → OUT_FOR_DELIVERY → DELIVERED or EXCEPTION.

shipment_charges

Duties, brokerage, surcharges, and delivery fees. Each charge has a payer (EXPORTER / IMPORTER / PLATFORM) and a payment status.

Data Model — Insurance

Three-stage lifecycle: Quote → Policy → Claim.

Data Model — Banking & Payments

bank_accounts

Accounts opened by a Bank member on behalf of any member. Types: OPERATING · CUSTODIAL · ESCROW · TRUST. Tracks available_balance and ledger_balance separately.

bank_transactions

Credits and debits against a bank account. Supports all six payment rails: SWIFT · ACH · SEPA · WIRE · INTERNAL · CRYPTO. Compliance-gated at write time. Has a compliance_hold flag for post-booking freezes.

fx_quotes

FX conversion quotes with rate, spread (bps), and fees. Can be executed (PATCH /fx-quotes/:id/execute) to lock the rate and produce a linked transaction.

payment_routes

Scored routing recommendations. Stored per request with all route options as JSON. Can be executed to create a bank transaction.

Data Model — Compliance

compliance_flags

Raised by Bank users against members, transactions, payments, or accounts. Severity levels:

• BLOCK — hard block, prevents any new remittance, bank transaction, or payment
• HIGH / MEDIUM / LOW — informational, do not gate operations

Flags flow through: OPEN → UNDER_REVIEW → RESOLVED or ESCALATED.

Data Model — Inspection

Data Model — Crypto / MooChedda

API Reference — System

Base path: /api. All requests and responses are JSON. Session token sent as x-session-token header or sessionToken in request body.

API Reference — Auth

API Reference — Members

API Reference — Products

API Reference — Import Orders

API Reference — Export

API Reference — Remittance

API Reference — Transport

API Reference — Insurance

API Reference — Banking

API Reference — Compliance

API Reference — Payment Routing

API Reference — Reconciliation

API Reference — Inspection

API Reference — Crypto / MooChedda

Service — Compliance Engine

File: src/services/compliance.js

Provides programmatic compliance checks and an Express middleware factory used to gate write operations.

Service — Payment Orchestrator

File: src/services/paymentOrchestrator.js

Scores all eligible payment rails for a given request. No I/O — pure computation.

score = baseCost + (amount × feeRate) + (settlementHours × urgencyWeight)

urgencyWeight: STANDARD=0.5 · EXPRESS=1.5 · URGENT=4.0

Rails: INTERNAL (score ≈ 0) → CRYPTO → SEPA → ACH → WIRE → SWIFT (highest cost). Currency and recipient-type constraints filter ineligible rails before scoring.

Service — Payment Rails

File: src/services/paymentRails.js

Validates and normalises per-rail payloads. Each rail has a spec defining required fields, currency constraints, amount ceilings, and rail-specific metadata (SEC codes for ACH, message type for SWIFT, scheme for SEPA, network for CRYPTO).

Service — Reconciliation Engine

File: src/services/reconciliation.js

Triggered via POST /reconciliation/run. Runs asynchronously via setImmediate after the 202 response is sent. Compares platform ledger records against bank transactions using amount tolerance of ±$0.01.

Scopes: FULL · REMITTANCES · IMPORTS · EXPORTS · ACCOUNTS. Results written to reconciliation_entries with one of: MATCHED · UNMATCHED · DISCREPANCY · NO_BANK_TXN.

Service — MooChedda SDK

File: src/services/moochedda.js

Zero external dependencies — uses Node built-in crypto, https, and http modules.

Signing

Transfer payloads are signed with secp256k1 ECDSA. The DER key is built programmatically from the 32-byte private key hex using ASN.1 encoding — no secp256k1 npm package required. The hash is SHA-256 of the concatenated string fromAddress + toAddress + amount + tokenSymbol.

TLS

Connections to v1.moochedda.com:3002 use rejectUnauthorized: false to tolerate custom certificates on the MooChedda host. This should be tightened in production by pinning the server certificate.

Environment Variables

Database Initialisation

# First run — create tables and optionally seed data
node src/seed.js

# Or run the server directly; schema.sql runs on startup
npm run dev        # development
npm start          # production (NODE_ENV=production)

The schema file uses CREATE TABLE IF NOT EXISTS and ALTER TABLE … ADD COLUMN IF NOT EXISTS throughout, so re-running it against an existing database is safe and idempotent.

Security Notes