PeerPay Architecture Overview¶

Welcome to the documentation for the PeerPay Blockchain infrastructure. This ecosystem is a set of interconnected repositories that together form a secure, highly available, and scalable enterprise blockchain solution built on Hyperledger Fabric.

This site explains how the following repositories work together:

High-Level Topology¶

The diagram below illustrates how the components of the PeerPay network interact with each other.

Diagram Legend¶

The labels in the diagram above (U, FE, API, etc.) are short node IDs used by Mermaid so the arrows can reference each box. They map to real components as follows:

Repository Roles¶

peerpay-saas-blockchain-explorer (Blockchain Explorer Frontend)¶

• Frontend UI for blockchain monitoring and operator actions.
• Calls Fabric API endpoints for loans, transfers, channels, blocks, and transactions.
• Default local endpoint: http://localhost:3000.
• See: Blockchain Explorer.

peerpay-saas-fabric-api (Fabric SaaS API)¶

• Main integration hub and backend.
• Handles authentication, request validation, business logic, explorer APIs, and Fabric interactions.
• Connects to:
  • Fabric network (chaincode invoke / query)
  • PostgreSQL (app / user / explorer metadata)
  • Kafka / MSK (event ingestion and publishing)
  • SMTP (notifications)
• Default endpoints: http://localhost:5000 or http://localhost:8080 depending on the Compose setup.
• See: Fabric SaaS API.

peerpay-fabric (Main Blockchain Network)¶

• Core Hyperledger Fabric network stack.
• Provides orderer, peers, CAs, channels, and deployed chaincodes.
• Main channels:
  • bankloan-channel
  • p2p-channel
• Chaincodes:
  • bankloan
  • p2ptransfer
• See: Main Fabric Network.

peerpay-enterprise-blockchain (Remote Enterprise Peer)¶

• Package for deploying a remote enterprise peer.
• Receives crypto material generated by the master network and joins existing channels.
• Allows federated org/peer participation without exposing CA internals publicly.
• See: Remote Enterprise Node.

peerpay-enterprise-orderer (High Availability Secondary Orderer)¶

• Standalone setup for deploying secondary orderer nodes (e.g. orderer2.example.com).
• Provides fault tolerance for the Raft consensus mechanism so the network has no single ordering point of failure.
• See: High Availability Orderer.

Communication Paths¶

1. Explorer → Fabric API

   • Protocol: HTTP/HTTPS REST
   • Purpose: UI actions and data retrieval

2. Fabric API → Fabric Network

   • Protocol: Fabric SDK (gRPC + TLS)
   • Purpose: submit / evaluate transactions and query ledger data

3. Fabric API → PostgreSQL

   • Protocol: SQL / TCP
   • Purpose: authentication and application state persistence

4. Fabric API → Kafka / MSK and SMTP

   • Protocol: SASL/TLS (Kafka), SMTP
   • Purpose: ingest async events and send notifications

5. Enterprise Peer → Master Fabric

   • Protocol: Fabric peer / orderer communication (gRPC + TLS)
   • Purpose: channel join, block replication, endorsement, gossip

6. Secondary Orderer → Master Fabric

   • Protocol: Raft consensus over gRPC + mTLS
   • Purpose: replicate the ordering state and provide fault-tolerant block production

End-to-End Runtime Flow¶

1. A user triggers an action in peerpay-saas-blockchain-explorer.
2. The frontend calls peerpay-saas-fabric-api (/api/...) with a JWT where required.
3. The API authenticates the request and routes it to the matching controller / service.
4. The service invokes or queries chaincode on bankloan-channel or p2p-channel.
5. Fabric peers endorse the transaction; the orderer cluster (primary + secondary) sequences it into a block.
6. The block propagates to all participating peers, including any remote enterprise peers joined to the channel.
7. The API returns a response to the frontend and may persist side metadata in PostgreSQL.

Enterprise Peer Onboarding Flow¶

1. The master node (peerpay-fabric) generates a remote-peer crypto bundle.
2. The bundle is transferred securely to the enterprise host.
3. peerpay-enterprise-blockchain extracts the crypto and applies environment configuration.
4. The remote peer starts and joins channels via the master orderer.
5. The remote peer participates in ledger sync and transaction endorsement (subject to channel policy).

For step-by-step instructions, see Remote Enterprise Node.

Architectural Note¶

In this architecture, peerpay-saas-fabric-api is the control and integration plane, while peerpay-fabric is the ledger plane. The explorer is the user-facing view, and the enterprise blockchain package extends network participation across external nodes. The secondary orderer keeps the ordering service highly available even if the primary node is offline.