# hyperledgerhandson/trade-finance-logistics architecture

> Architecture diagram of the GitHub repository hyperledgerhandson/trade-finance-logistics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyperledgerhandson/trade-finance-logistics
- Repository: https://github.com/hyperledgerhandson/trade-finance-logistics

## Overview

##### Main Components
- Chaincode (Smart Contracts): This is found in the “chaincode” directory and contains the smart contract logic (for example, the trade workflow, access control, and asset management). Include both versions (trade_workflow and trade_workflow_v1) to indicate upgradeability.
- Middleware: Encapsulated in the “middleware” folder, these wrapper functions use the Fabric SDK to perform channel operations, chaincode installation, instantiation, upgrades, and running trade scenarios. They act as a bridge between the application and the blockchain network.
- Application Server: Located in the “application” directory, this component starts a web server exposing a REST API, handles user registration/login, and initiates operations such as channel setup and chaincode upgrades.
- Composer: Although its role is slightly different from the others, the “composer” folder seems to support business logic and modelling (possibly using Hyperledger Composer tools). It defines additional business rules or assets and includes features, models, and ACL configurations.
- Network: The “network” directory comprises configuration files, Docker Compose files, and scripts that set up the actual blockchain environment (peers, Orderer, and Certificate Authority) using Hyperledger Fabric configurations.

##### Relationships and Data Flow
- The Application Server sends REST API requests which invoke middleware functions.
- Middleware uses the Fabric SDK to interact with the blockchain network. This layer submits transactions to installed chaincode on the Fabric network.
- The blockchain network (configured via Docker and related configuration files in “network”) executes chaincode operations as received from middleware.
- For scenarios like chaincode upgrades or adding a new organization, both the middleware and network components are involved, with instructions provided to update configuration files and trigger changes through the application server.
- Composer may integrate into the workflow by defining assets, business network definitions, and permissions, which are then enforced and utilized by chaincode.

##### Architectural Patterns and Design Principles
- Layered Architecture: Separate concerns by distinguishing between user interface/REST layer (application), business logic integration (middleware), and on-chain logic (chaincode).
- Microservices-like Separation: Even though the system is interconnected, each folder (chaincode, middleware, application, network, composer) clearly represents a self-contained module. This modularity supports upgradeability (e.g., new chaincode versions) and scaling.
- Use of Blockchain-Specific Patterns: The chaincode implements business logic that enforces trust between multiple parties using Hyperledger Fabric’s mechanisms like Attribute Based Access Control (ABAC).

##### Incorporate Relevant Technologies and Frameworks
- Hyperledger Fabric: For blockchain network, peer nodes, chaincode (smart contract) execution, and network configuration.
- Fabric SDK: Utilized in the middleware layer for operations like channel management, chaincode installation/upgrade, and transaction submission.
- REST API/Web Server Framework(s): Used in the “application” folder to expose endpoints for user interactions.
- Docker / Docker Compose: For deploying the network as containerized services.
- Hyperledger Composer (if applicable): For modeling organizational assets and permissions.

##### Elements
- Use clear labels for each component: Chaincode (Smart Contracts), Middleware (Blockchain SDK Wrappers), Application (REST API Server), Composer (Business Network Definitions), and Network (Hyperledger Fabric setup).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application Layer"
        APP["Application Server (REST API)"]:::application
    end

    subgraph "Middleware Layer"
        MW["Middleware (Blockchain SDK Wrappers)"]:::middleware
        INV["Invoke Chaincode (invoke-chaincode.js)"]:::middlewareDetail
        INS["Install Chaincode (install-chaincode.js)"]:::middlewareDetail
    end

    subgraph "Blockchain Layer"
        subgraph "Chaincode (Smart Contracts)"
            TW["Trade Workflow"]:::chaincode
            TWv1["Trade Workflow V1"]:::chaincode
        end
        COM["Composer (Business Network Definitions)"]:::composer
    end

    subgraph "Network Configuration"
        NET["Network (Hyperledger Fabric Configuration)"]:::network
    end

    %% Relationships and Data Flow
    APP -->|"REST_API_Request"| MW
    MW -->|"Calls"| INV
    MW -->|"Calls"| INS
    MW -->|"Submits_Transaction"| TW
    MW -->|"Triggers_Upgrade"| TWv1
    TW -->|"Executes_on"| NET
    TWv1 -->|"Executes_on"| NET
    COM -->|"Defines_assets&rules"| TW
    MW -.->|"Chaincode_Upgrade"| NET

    %% Click Events
    click APP "https://github.com/hyperledgerhandson/trade-finance-logistics/blob/master/application/app.js"
    click MW "https://github.com/hyperledgerhandson/trade-finance-logistics/tree/master/middleware/"
    click INV "https://github.com/hyperledgerhandson/trade-finance-logistics/blob/master/middleware/invoke-chaincode.js"
    click INS "https://github.com/hyperledgerhandson/trade-finance-logistics/blob/master/middleware/install-chaincode.js"
    click TW "https://github.com/hyperledgerhandson/trade-finance-logistics/tree/master/chaincode/src/github.com/trade_workflow"
    click TWv1 "https://github.com/hyperledgerhandson/trade-finance-logistics/tree/master/chaincode/src/github.com/trade_workflow_v1"
    click COM "https://github.com/hyperledgerhandson/trade-finance-logistics/tree/master/composer/"
    click NET "https://github.com/hyperledgerhandson/trade-finance-logistics/tree/master/network/"

    %% Styles
    classDef application fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef middleware fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef middlewareDetail fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef chaincode fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef composer fill:#FADBD8,stroke:#CB4335,stroke-width:2px;
    classDef network fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
```
