# hernanjh/bfa.apitsa1 architecture

> Architecture diagram of the GitHub repository hernanjh/bfa.apitsa1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hernanjh/bfa.apitsa1
- Repository: https://github.com/hernanjh/bfa.apitsa1

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Clients
    Client["External Clients"]:::external

    %% Container Boundary
    subgraph "Docker Container"
        direction TB

        %% API Layer
        subgraph "API Layer"
            direction TB
            ExpressServer["Express Server<br/>(server.js)"]:::api
            Routes["Routes Definition<br/>(api/routes.js)"]:::api
        end

        %% Controller Layer
        subgraph "Controller Layer"
            direction TB
            Controller["Business Logic Controller<br/>(api/bfacontroller.js)"]:::controller
        end

        %% Service/Utils Layer
        subgraph "Service Layer"
            direction TB
            Utils["Web3 Utils<br/>(api/utils.js)"]:::service
            Config["Configuration<br/>(api/config.js)"]:::config
        end

        %% Containerization Files
        subgraph "Containerization Artifacts" 
            direction TB
            DockerfileNode["Dockerfile"]:::infra
            DockerCompose["docker-compose.yml"]:::infra
            DockerIgnore[".dockerignore"]:::infra
        end

        %% Package & Docs
        subgraph "Project Metadata"
            direction TB
            Package["package.json"]:::infra
            Readme["README.md"]:::infra
        end
    end

    %% External Blockchain
    subgraph "Blockchain Infrastructure"
        direction TB
        BlockchainNode["Blockchain Node (opentx)"]:::blockchain
        SmartContract["Smart Contract"]:::blockchain
    end

    %% Connections
    Client -->|HTTP| ExpressServer
    ExpressServer -->|mounts routes| Routes
    Routes -->|calls| Controller
    Controller -->|uses| Utils
    Utils -->|reads config| Config
    Utils -->|JSON-RPC| BlockchainNode
    BlockchainNode -->|executes| SmartContract
    SmartContract -->|response| BlockchainNode
    BlockchainNode -->|returns| Utils
    Utils -->|result| Controller
    Controller -->|HTTP response| Client

    %% Click Events
    click ExpressServer "https://github.com/hernanjh/bfa.apitsa1/blob/main/server.js"
    click Routes "https://github.com/hernanjh/bfa.apitsa1/blob/main/api/routes.js"
    click Controller "https://github.com/hernanjh/bfa.apitsa1/blob/main/api/bfacontroller.js"
    click Utils "https://github.com/hernanjh/bfa.apitsa1/blob/main/api/utils.js"
    click Config "https://github.com/hernanjh/bfa.apitsa1/blob/main/api/config.js"
    click DockerfileNode "https://github.com/hernanjh/bfa.apitsa1/tree/main/Dockerfile"
    click DockerCompose "https://github.com/hernanjh/bfa.apitsa1/blob/main/docker-compose.yml"
    click DockerIgnore "https://github.com/hernanjh/bfa.apitsa1/blob/main/.dockerignore"
    click Package "https://github.com/hernanjh/bfa.apitsa1/blob/main/package.json"
    click Readme "https://github.com/hernanjh/bfa.apitsa1/blob/main/README.md"

    %% Styles
    classDef external fill:#E8F0FF,stroke:#1F4E79,stroke-width:2px
    classDef api fill:#CCE5FF,stroke:#2E75B6,stroke-width:2px
    classDef controller fill:#D5E8D4,stroke:#82B366,stroke-width:2px
    classDef service fill:#FFF2CC,stroke:#D79B00,stroke-width:2px
    classDef config fill:#F2F2F2,stroke:#7F7F7F,stroke-width:2px
    classDef blockchain fill:#FFE699,stroke:#BF9000,stroke-width:2px
    classDef infra fill:#F4F4F4,stroke:#A6A6A6,stroke-width:2px
```
