# sosane/agriculture-product-tracking-chain architecture

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

- Interactive diagram: https://gitdiagram.com/sosane/agriculture-product-tracking-chain
- Repository: https://github.com/sosane/agriculture-product-tracking-chain

## Overview

##### Project type and purpose
- AgriChain is a full-stack, blockchain-enabled supply-chain tracking system for agricultural products.
- It consists of:
- A React/Vite frontend (customer/admin dashboards, QR scanning, data visualization)
- A Node.js/Express backend exposing a REST API and managing sessions
- A PostgreSQL database for user/product metadata
- Solidity smart contracts deployed via Hardhat on an Ethereum testnet
- QR‐code based verification against on‐chain data

##### File structure
Top-level directories:
- agrichain-frontend-react/agrichain-frontend → React/Vite UI
- agrichain-backend/ → Express server, domain-driven controllers, services
- agrichain-database/ → SQL scripts for schema and initialization
- agrichain-smartcontract/ → Solidity contracts, Hardhat config, deployment scripts
Other files: LICENSE, root README, assets (screenshots)

##### Key architectural insights from README
- Frontend runs on port 5173, interacts with backend (port 5000) via REST + directly with blockchain through Ethers.js
- Backend connects to PostgreSQL and to Ethereum node (Hardhat) to call contracts
- Smart contracts handle ownership transfer, certification, supply chain events
- PostgreSQL stores off-chain metadata, sessions, user accounts

##### Main components
a. Clients & UI
- Web Browser / React App
- QR Scanner / Mobile camera (web)
b. Frontend Layer
- React pages & components
- Service modules (authService, productService, contractService)
c. Backend Layer
- Express server (index.js, server.js)
- Domain modules (User, Product controllers/routes/models)
- ContractServices and utility modules
d. Persistence & On-chain
- PostgreSQL database (agrichain schema)
- Ethereum network (Hardhat local node)
- Smart contracts (Deployed address)
e. External services
- MetaMask / Wallet
- CORS origin (frontend → backend)

##### Relationships & data flows
- User interacts with React UI → REST API calls to backend endpoints → controllers invoke domain services → queries to PostgreSQL or on-chain transactions via contractServices → responses back to UI.
- For blockchain reads/writes:
- Frontend contractService uses Ethers.js to call smart contracts on Ethereum node.
- Backend contractServices uses admin private key to send transactions or read events.
- QR Scanner triggers frontend to fetch on-chain product history, calling either backend or directly contractService.

##### Architectural patterns & principles
- Separation of concerns: UI / API / data / blockchain layers
- Domain-driven design in backend (per-domain controllers/models/routes)
- Single-page application with REST + direct blockchain calls
- Immutable event sourcing on blockchain vs. mutable relational storage

##### Detailed elements to capture
- Frontend: service modules, pages, hooks
- Backend: env/config, domain folders, utils/generator
- Smart contracts: artifacts vs. source, deploy script
- Database: init.sql, schema.sql
- Environment variables (e.g., CONTRACT_ADDRESS, BLOCKCHAIN_PROVIDER_URL)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    User(["User (Admin/Farmer/Regulator)"]):::actor
    MetaMask(["MetaMask Wallet"]):::actor

    %% Frontend Layer
    subgraph "Frontend Layer" 
        direction TB
        ReactApp["Browser/React App"]:::ui
        AppShell["React Application Shell"]:::ui
        Pages["Frontend Pages"]:::ui
        Layout["Layout Components"]:::ui
        ProductComp["Product Components"]:::ui
        VerificationComp["Verification Components"]:::ui
        FServices["Frontend Service Modules"]:::ui
        Hooks["Frontend Custom Hooks"]:::ui
        FConfig["Frontend Configuration"]:::ui
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        ExpressServer["Express Server"]:::api
        DBConfig["Backend Database Configuration"]:::api
        UserModule["User Domain Module"]:::api
        ProductModule["Product Domain Module"]:::api
        ContractSrv["Backend Contract Service"]:::api
        UtilsGen["Backend Utility Generators"]:::api
        EnvExample["Backend Environment Example"]:::api
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        subgraph "Off-chain Storage"
            direction TB
            Postgres["PostgreSQL Database"]:::db
            SchemaSQL["PostgreSQL Schema Script"]:::db
            InitSQL["Database Initialization Script"]:::db
        end
        subgraph "On-chain Network"
            direction TB
            HardhatNode["Hardhat Local Ethereum Node"]:::chain
            ContractsSrc["Solidity Contracts (source)"]:::chain
            HardhatCfg["Hardhat Configuration"]:::chain
            DeployScript["Smart Contract Deployment Script"]:::chain
            Artifacts["Compiled Artifacts"]:::chain
        end
    end

    %% Connections - User interactions
    User -->|uses| ReactApp
    MetaMask -->|injects Web3| ReactApp

    %% Frontend internal structure
    ReactApp -->|renders| AppShell
    AppShell --> Pages
    AppShell --> Layout
    Pages --> ProductComp
    Pages --> VerificationComp
    AppShell --> Hooks
    AppShell --> FServices
    AppShell --> FConfig

    %% Frontend to Backend & Blockchain
    ReactApp -->|"HTTP REST"| ExpressServer
    ReactApp -->|"JSON-RPC via Ethers.js"| HardhatNode

    %% Backend flows
    ExpressServer -->|uses| EnvExample
    ExpressServer -->|"connect"| DBConfig
    ExpressServer -->|routes to| UserModule
    ExpressServer -->|routes to| ProductModule
    UserModule -->|queries| Postgres
    ProductModule -->|queries| Postgres
    ExpressServer -->|calls| ContractSrv
    ContractSrv -->|"JSON-RPC"| HardhatNode
    ContractSrv -->|reads events| Artifacts
    ExpressServer -->|imports| UtilsGen

    %% Persistence init scripts
    SchemaSQL --> Postgres
    InitSQL --> Postgres

    %% On-chain deployment
    ContractsSrc --> HardhatCfg
    HardhatCfg --> DeployScript
    DeployScript -->|deploys| ContractsSrc
    DeployScript -->|produces| Artifacts
    DeployScript -->|connects to| HardhatNode

    %% Click Events
    click ReactApp "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-frontend-react/agrichain-frontend/src/main.tsx"
    click ReactApp "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-frontend-react/agrichain-frontend/index.html"
    click AppShell "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-frontend-react/agrichain-frontend/src/App.tsx"
    click Pages "https://github.com/sosane/agriculture-product-tracking-chain/tree/main/agrichain-frontend-react/agrichain-frontend/src/pages"
    click Layout "https://github.com/sosane/agriculture-product-tracking-chain/tree/main/agrichain-frontend-react/agrichain-frontend/src/components/layout"
    click ProductComp "https://github.com/sosane/agriculture-product-tracking-chain/tree/main/agrichain-frontend-react/agrichain-frontend/src/components/product"
    click VerificationComp "https://github.com/sosane/agriculture-product-tracking-chain/tree/main/agrichain-frontend-react/agrichain-frontend/src/components/verification"
    click FServices "https://github.com/sosane/agriculture-product-tracking-chain/tree/main/agrichain-frontend-react/agrichain-frontend/src/services"
    click Hooks "https://github.com/sosane/agriculture-product-tracking-chain/tree/main/agrichain-frontend-react/agrichain-frontend/src/hooks"
    click FConfig "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-frontend-react/agrichain-frontend/vite.config.ts"
    click FConfig "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-frontend-react/agrichain-frontend/tailwind.config.js"
    click FConfig "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-frontend-react/agrichain-frontend/tsconfig.json"
    click ExpressServer "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-backend/src/index.js"
    click ExpressServer "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-backend/src/server.js"
    click DBConfig "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-backend/src/config/db.js"
    click UserModule "https://github.com/sosane/agriculture-product-tracking-chain/tree/main/agrichain-backend/src/domains/user"
    click ProductModule "https://github.com/sosane/agriculture-product-tracking-chain/tree/main/agrichain-backend/src/domains/product"
    click ContractSrv "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-backend/src/services/contractServices.js"
    click UtilsGen "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-backend/src/utils/generator.js"
    click EnvExample "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-backend/.env.example"
    click SchemaSQL "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-database/commands/schema.sql"
    click InitSQL "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-database/init.sql"
    click ContractsSrc "https://github.com/sosane/agriculture-product-tracking-chain/tree/main/agrichain-smartcontract/contracts"
    click HardhatCfg "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-smartcontract/hardhat.config.js"
    click DeployScript "https://github.com/sosane/agriculture-product-tracking-chain/blob/main/agrichain-smartcontract/scripts/deploy.js"
    click Artifacts "https://github.com/sosane/agriculture-product-tracking-chain/tree/main/agrichain-smartcontract/artifacts"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef api fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef db fill:#FFE7A2,stroke:#333,stroke-width:1px
    classDef chain fill:#E4DAFF,stroke:#333,stroke-width:1px
    classDef actor fill:#CCCCCC,stroke:#333,stroke-width:1px
```
