How hernanjh/bfa.apitsa1 works
Project Type and Purpose
• This is a standalone backend‐only microservice: a REST API built with Node.js and Express that provides timestamp (“stamp”) and verification (“verify”) endpoints by interacting with an external Ethereum‐style blockchain node (opentx). It runs either directly on a server or in Docker/Compose.
File Structure Analysis
• Top‐level files:
• server.js – boots the Express app and mounts API routes
• Dockerfile, .dockerignore, docker-compose.yml – containerization artifacts
• package.json – Node dependencies (Express, Web3 or similar)
• api/ directory:
• routes.js – Express router definitions for /stamp, /verify, /balance, /block, /tx
• bfacontroller.js – handlers that implement each endpoint’s logic
• utils.js – Web3 wrapper functions for JSON‐RPC calls
• config.js – environment configuration (account, private key, node URL)
README Insights
• Uses Express as the HTTP framework.
• Communicates with a blockchain node over JSON‐RPC to:
a. Stamp a file hash into a smart contract
b. Verify a previously created RD (receipt data)
c. Expose generic endpoints for balance, block, and transaction data
a. Main Components
1. External Clients – any service or UI invoking the REST endpoints
2. API Layer (Express server)
• server.js
• routes.js
3. Controller Layer (bfacontroller.js)
• Implements business logic per endpoint
4. Service/Utils Layer (utils.js)
• Wraps Web3 or JSON‐RPC calls to the blockchain node
5. Configuration (config.js)
• Supplies account address, private key, RPC URL
6. External Blockchain Node (opentx)
• Hosts the smart contract and responds to JSON‐RPC requests
7. Smart Contract on Chain
• Provides functions stamp(), verify(), getHash(), getBlockNumber()
8. Containerization
• Dockerfile and docker-compose.yml define the runtime environment
b. Relationships and Data Flows
• Client → HTTP → Express routes
• Routes → call Controller functions
• Controllers → call Utils (Web3) methods using config
• Utils → JSON‐RPC requests → Blockchain node
• Blockchain node → executes smart contract calls/transactions → returns result
• Controllers → transform results → HTTP response → Client
c. Architectural Patterns and Principles
• Layered Architecture: clear separation between HTTP routing, business logic, and external service interaction
• Configuration via environment variables (12-factor app)
• Stateless microservice: no internal database; state persisted on blockchain
• Containerized deployment for portability & isolation
d. Key Technologies
• Node.js + Express
• Web3 or Ethereum JSON‐RPC client
• Docker / Docker Compose
• Ethereum smart contract ABI
Essential Elements
• Component names: Express Server, Routes, Controller, Web3 Utils, Config, Blockchain Node, Smart Contract
• Data flows: “POST /stamp → Controller.stamp() → Web3.eth.sendTransaction → Smart Contract”
• Environment variables injected into the container (ACCOUNTADDRESS, ACCOUNTPRIVATEKEY, SERVER)