# akdoganalibugra/blockchain-api-node architecture

> Architecture diagram of the GitHub repository akdoganalibugra/blockchain-api-node, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akdoganalibugra/blockchain-api-node
- Repository: https://github.com/akdoganalibugra/blockchain-api-node

## Overview

##### Project Type and Purpose
- This is a Node.js API developed in TypeScript that interacts with a blockchain network. The project is designed to provide secure and scalable API endpoints for decentralized application needs.
- The README indicates it’s primarily a test/development project that provides a blockchain API, while the contracts directory and use of Hardhat suggest that blockchain smart contracts are also part of the project.

##### Analyzing the File Structure
- Top-Level Files/Folders:
- .env, .gitignore, package.json, package-lock.json, tsconfig.json: Standard configuration and environment setup.
- README.md, project-overview.md, usage.md: Documentation and usage instructions.
- Contracts & Hardhat:
- The "contracts" folder likely holds smart contract code. The "hardhat.config.ts" indicates the blockchain development environment.
- Scripts:
- Scripts folder (with deploy.js and reward-user.js) contains automation scripts such as deploying contracts and handling user rewards.
- Source Code (src folder):
- "config": Contains configuration files for swagger API documentation and web3Connection setup, highlighting connections to blockchain networks.
- "controllers": Contains the rewardController.ts which likely manages incoming API requests related to rewards.
- "docs": Contains swagger documentation satisfying API documentation requirement.
- "routes": Defines the API endpoints (health-check and reward routes).
- "services": Business logic; includes address and reward services.
- "utils": Helper functions, for example, API response formatting.
- Testing:
- The "test" folder includes test scripts, in this case for contract testing.

##### Main Components
- API Server Component:
- Represented by the main entry point (src/index.ts) which initializes the server and routes.
- Components under “controllers”, “routes” and “services” should be displayed.
- Configuration and Utility Modules:
- Components for swagger (API documentation) and web3 connections, ensuring integration with blockchain.
- Blockchain Integration:
- “contracts” directory and the Hardhat configuration that represents the smart contract development environment.
- Scripts and Deployment:
- Deployment and reward scripts showing tasks that interface with contracts.
- Testing Framework:
- Components representing the test suites, reinforcing quality assurance.

##### Relationships & Interactions
- Data flow starting with API requests hitting the "routes" which then call respective "controllers".
- Controllers communicate with "services" for business logic.
- The "services" layer, in turn, interacts with external blockchain networks via the "web3Connection.ts" service.
- Deployment and management scripts demonstrate how smart contracts (in the contracts directory) are deployed and interacted with.
- Swagger documentation (from “config/swagger.ts” and “docs/reward.swagger.ts”) is integrated to provide API documentation and client interactions.

##### Architectural Patterns & Design Principles
- This project follows a layered architecture (separating routing, controllers, and services) which is common in API designs.
- Emphasizes separation of concerns: Routes handle HTTP details; controllers manage request handling; and services encapsulate business logic.
- It also integrates blockchain interactions as external service components.
- Utilizes configuration files and dependency injection approaches in the config modules to manage environmental and blockchain connection details.

##### Details
- API requests flowing from the client into the API Server → Routes → Controllers → Services.
- Service interaction with the blockchain (e.g., transactions via web3).
- Configuration being loaded into application startup (from config modules).
- API components.
- Blockchain-related components.
- Utility and configuration modules.
- Deployment and test scripts.

Final Tips:
- Then zoom into each major component cluster to show individual files/folders (e.g., show how rewardController, rewardService, and routes interact).
- Use the information in the README (and the links to project-overview and usage.md) to confirm any additional runtime behavior or environment-specific details.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    client["API Consumer"]:::external

    %% API Core Layer
    subgraph "API Core Layer"
        index["API Server: Entry Point"]:::api
        subgraph "Routes"
            hc["Health-Check Route"]:::api
            rr["Reward Route"]:::api
        end
        ctrl["Reward Controller"]:::api
        subgraph "Services"
            asrv["Address Service"]:::api
            rsrv["Reward Service"]:::api
        end
    end

    %% Configuration & Utilities Layer
    subgraph "Configuration & Utilities Layer"
        sc["Swagger Config"]:::config
        web3["Web3 Connection Module"]:::config
        utils["API Response Utils"]:::utils
    end

    %% API Documentation
    subgraph "API Documentation"
        readme["README Documentation"]:::docs
        overview["Project Overview"]:::docs
        usage["Usage Documentation"]:::docs
        rsw["Reward Swagger Docs"]:::docs
    end

    %% Blockchain Integration Layer
    subgraph "Blockchain Integration Layer"
        contracts["Smart Contracts"]:::blockchain
        hardhat["Hardhat Config"]:::blockchain
    end

    %% Deployment & Testing Layer
    subgraph "Deployment & Testing Layer"
        deploy["Deploy Script"]:::scripts
        rewardScript["Reward User Script"]:::scripts
        tests["Contract Tests"]:::test
    end

    %% Connections
    client -->|"sends request"| index
    index -->|"routes"| hc
    index -->|"routes"| rr
    hc -->|"triggers"| ctrl
    rr -->|"triggers"| ctrl
    ctrl -->|"calls"| rsrv
    rsrv -->|"uses"| asrv
    rsrv -->|"calls"| web3
    web3 -->|"transacts"| contracts
    web3 -->|"configuresVia"| hardhat
    index -->|"loads"| sc
    index -->|"uses"| utils
    sc -->|"documents"| readme
    sc -->|"documents"| overview
    sc -->|"documents"| usage
    sc -->|"documents"| rsw
    deploy -->|"deploys"| contracts
    rewardScript -->|"invokes"| contracts
    tests -->|"validates"| contracts
    tests -->|"uses"| hardhat

    %% Click Events
    click index "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/src/index.ts"
    click hc "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/src/routes/health-check.routes.ts"
    click rr "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/src/routes/reward.routes.ts"
    click ctrl "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/src/controllers/rewardController.ts"
    click asrv "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/src/services/address.service.ts"
    click rsrv "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/src/services/reward.service.ts"
    click sc "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/src/config/swagger.ts"
    click web3 "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/src/config/web3Connection.ts"
    click contracts "https://github.com/akdoganalibugra/blockchain-api-node/tree/master/contracts"
    click hardhat "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/hardhat.config.ts"
    click deploy "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/scripts/deploy.js"
    click rewardScript "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/scripts/reward-user.js"
    click tests "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/test/contract.test.js"
    click readme "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/README.md"
    click overview "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/project-overview.md"
    click usage "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/usage.md"
    click rsw "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/src/docs/reward.swagger.ts"
    click utils "https://github.com/akdoganalibugra/blockchain-api-node/blob/master/src/utils/api.response.utils.ts"

    %% Class Definitions for Colour Coding
    classDef api fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef blockchain fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef config fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef scripts fill:#F5CBA7,stroke:#CB4335,stroke-width:2px;
    classDef test fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef docs fill:#FAE5D3,stroke:#D35400,stroke-width:2px;
    classDef utils fill:#E8DAEF,stroke:#7D3C98,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
