Architecture

Architecture

architecture
Fig.1 BESSE architecture
mindmap
Fig.2 BESSE mindmap

The architecture is divided into four major components: the web frontend, the mobile app, the backend, and the blockchain layer.

System Architecture Overview

BESSE follows a modern, decentralized architecture that combines traditional web technologies with blockchain infrastructure. The system is designed to be scalable, secure, and transparent, enabling seamless interaction between users, smart contracts, and backend services.

Frontend

The frontend is built as a single-page application (SPA) using modern React-based technologies:

  • React 18 (opens in a new tab) - A free and open-source front-end JavaScript library for building user interfaces based on UI components. It is maintained by Meta and a community of individual developers and companies. React serves as the foundation for building interactive, component-based user interfaces.

  • Redux Toolkit (opens in a new tab) - The official, opinionated, batteries-included toolset for efficient Redux development. It provides a standardized way to write Redux logic, making it easier to manage complex application state, handle async operations, and speed up development with recommended best practices baked in.

  • React Router v6 (opens in a new tab) - Declarative routing for React applications, enabling navigation between different views and components while maintaining application state.

  • Ethers.js v5 (opens in a new tab) - A complete Ethereum library and wallet implementation in JavaScript. Used for interacting with smart contracts, managing wallet connections, and handling blockchain transactions.

  • Tailwind CSS (opens in a new tab) - A utility-first CSS framework packed with classes that can be composed to build any design directly in markup. The final bundle only includes classes used in the application, making it significantly smaller and faster.

  • Framer Motion (opens in a new tab) - A production-ready motion library for React, providing smooth animations and transitions for enhanced user experience.

  • Chart.js (opens in a new tab) - A powerful data visualization library used for displaying environmental impact metrics, economic data, and analytics on the dashboard.

  • Vite (opens in a new tab) - Next-generation frontend build tool that provides fast development server and optimized production builds.

Mobile App

The companion mobile app brings the marketplace to iOS and Android from a single codebase (see Mobile App):

  • React Native (Expo) with TypeScript — shares the backend, data model, and Redux patterns with the web app
  • Expo Router — file-based navigation with deep linking
  • Live data via Firestore subscriptions, with sessions and reference data persisted on-device for offline tolerance
  • Native capabilities — Apple/Google Maps, GPS tracking for shipments, camera & QR scanning, secure storage
  • Contains no smart-contract ABIs: privileged blockchain operations go through the same cloud functions as the web app

Backend (Firebase) (opens in a new tab)

The backend leverages Google's Firebase platform for serverless infrastructure:

  • Firebase Authentication - Provides backend services and easy-to-use SDKs for user authentication. BESSE uses custom-token authentication with two entry paths: wallet-signature login (MetaMask) and social login via Privy — Google/email with an automatically provisioned embedded wallet. Both mint the same Firebase session keyed by the wallet address.

  • Cloud Firestore - A flexible, scalable NoSQL cloud database that stores and syncs data for client and server-side development. Used for:

    • User profiles and role assignments
    • Auction metadata and status
    • Asset information and tracking events
    • WARM configuration and material mappings
    • Transaction history

  • Cloud Functions (Node.js 20) - A serverless, event-driven computing service within Google Cloud Platform. Functions handle:

    • Authentication (nonce generation, signature verification)
    • Smart contract deployment and interaction
    • WARM model calculations and analysis
    • Asset creation and management
    • Auction lifecycle management
    • Scheduled tasks (e.g., auction completion)

  • Firebase Emulators - Local development environment for testing Firebase services without connecting to production.

Blockchain Interaction

The blockchain layer provides decentralized, trustless execution of auctions and asset transfers:

  • MetaMask - Browser extension wallet that enables users to interact with the Ethereum blockchain. Handles:

    • Wallet connection and account management
    • Transaction signing and approval
    • Network switching (Polygon, Sepolia, Localhost)
    • Balance queries

  • Hardhat - Development environment for Ethereum smart contracts. Provides:

    • Local blockchain network for testing
    • Contract compilation and deployment
    • Testing framework integration
    • Network configuration management

  • Solidity Smart Contracts:

    • AuctionFactory.sol - Factory contract that creates and manages auction instances
    • DutchAuction.sol - Implements descending price auction logic
    • EnglishAuction.sol - Implements ascending price auction logic
    • FixedPriceSale.sol - Implements fixed-price direct sales
    • ERC721Mintable.sol - NFT standard implementation for asset representation

  • Ethers.js - JavaScript library for interacting with Ethereum blockchain:

    • Contract instance creation and method calls
    • Transaction sending and monitoring
    • Event listening and filtering
    • Signature verification for authentication

  • Unit Testing - Waffle, Mocha & Chai for comprehensive smart contract testing

Integration Services

  • WARM Model Integration:

    • SheetJS - Converts WARM Excel spreadsheets to JavaScript objects
    • HyperFormula - Executes spreadsheet formulae without MS Excel
    • WARM API - Public REST API for WARM calculations

  • QR Code System:

    • QR code generation for asset tracking
    • Scanner integration for mobile and web
    • Location tracking and event logging

Data Flow

  1. User Registration: User signs in with Google/email via Privy (embedded wallet auto-created) or connects MetaMask (backend issues a nonce → user signs → backend verifies) → Firebase custom token minted → User profile created in Firestore

  2. Asset Creation: User creates asset → NFT minted on blockchain → Asset metadata stored in Firestore → QR code generated

  3. Auction Creation: User creates auction → Smart contract deployed → Auction data stored in Firestore → WARM calculations performed → Auction listed on frontend

  4. Bidding: User places bid → Transaction sent to blockchain → Smart contract validates bid → Firestore updated with bid information → Frontend reflects new bid

  5. Auction Completion: Auction ends → Smart contract determines winner → NFT transferred to winner → Payment held in the contract's escrow → Buyer confirms delivery (7-day fallback for the seller) → Funds released → Firestore updated with final status

  6. Asset Tracking: User scans QR code → Tracking event recorded in Firestore → Location and timestamp captured → Supply chain history updated

Network Support

BESSE supports multiple blockchain networks:

  • Sepolia Testnet (Chain ID: 11155111) - Current pilot deployment target
  • Localhost (Chain ID: 1337) - Local Hardhat network for development
  • Polygon Amoy Testnet (Chain ID: 80002) - Supported test network
  • Polygon Mainnet (Chain ID: 137) - Planned production network

The application automatically detects and switches to the configured network based on environment variables.

Get StartedMobile App