# koya-tech/simple-shop-dapps architecture

> Architecture diagram of the GitHub repository koya-tech/simple-shop-dapps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/koya-tech/simple-shop-dapps
- Repository: https://github.com/koya-tech/simple-shop-dapps

## Overview

1. The “blockchain” directory contains everything related to smart contracts and blockchain interactions:
- Smart contracts written in Solidity.
- Hardhat configuration and deployment scripts (see hardhat.config.ts, ignition modules like Lock.ts and PurchaseHistory.ts).
- Automated tests for smart contracts.

##### The “shop-app” directory handles the user-facing frontend
- Built with Next.js, React, and TypeScript.
- Contains pages for products, the shopping cart, and an admin view to manage or view the purchase history.
- Integrates with external services (FakeStore API for product data) and custom hooks such as useBlockchain.ts to interact with the blockchain components.

- Frontend Application (shop-app)
- User Interface: Includes pages for product listing, individual product detail, cart, and admin page.
- UI Components: Such as Header, Footer, ProductTab, etc.
- State Management: Cart store and hooks to manage UI state (e.g., cartStore.ts, use-toast.ts).
- External API Integration: Connecting to FakeStore API to fetch product data.
- Blockchain Interaction: A custom hook (useBlockchain.ts) responsible for wallet interactions (MetaMask connection) and communication with smart contracts.

- Blockchain Backend (blockchain)
- Smart Contracts: Modules like PurchaseHistory and Lock in the ignition directory.
- Hardhat Environment: Configuration, deployment scripts, and local blockchain network setup.
- Test Suite: Testing for contract functionality.

- External Services:
- FakeStore API: Supplies product information.
- MetaMask: Connects users’ wallets to the dapp for authorizing transactions.

B. Map the relationships and interactions:
- The User Interface (shop-app) communicates with:
- The FakeStore API to fetch product listings.
- The blockchain backend through the blockchain hook (useBlockchain.ts) to trigger smart contract interactions.
- The blockchain component:
- Records purchase data on the Ethereum blockchain using smart contracts.
- Provides endpoints (through contract functions) that are invoked by the frontend (web3 calls via MetaMask).
- The admin page in the shop-app uses blockchain queries (or calls) to retrieve the purchase history stored on-chain.

C. Highlight key architectural patterns and design principles:
- Separation of Concerns: The project is clearly divided into a blockchain sub-project and a frontend web application.
- Client-Blockchain Decoupling: The frontend handles user interaction and integrates with the blockchain for persistent storage of purchase data.
- Use of Modern Frameworks: Next.js for SSR/SSG and Hardhat for smart contract management.
- Secure Smart Contract Deployment: Emphasis on security best practices in smart contract design, as noted in the README.

D. Include technologies, frameworks, and libraries:
- Frontend: Next.js, React, Tailwind CSS, TypeScript.
- Blockchain: Solidity, Hardhat, Ethereum.
- External API: FakeStore API.
- Wallet Interaction: MetaMask integration for user authentication and transaction signing.

1. Create high-level blocks for each major module:
- Shop App (Frontend)
- Blockchain (Smart Contracts)
- External Services (FakeStore API, MetaMask)
- Data flow from the frontend to the blockchain (for purchase transactions).
- API calls from the frontend to the FakeStore API.
- Wallet interactions between the user’s browser (via MetaMask) and the blockchain.
- Another for blockchain-related components.
- A third for external dependencies/APIs.
5. Additional notes or sub-components, such as:
- Breakdown of the shop-app pages and components.
- The separation between public pages (product listings, cart) and admin functionalities for viewing purchase history.
6. Deployment and configuration aspects:
- Deployment of smart contracts using Hardhat.
- Environment variables (contract address, ABI) linking the frontend to the deployed contracts.

- Integration point between the blockchain contracts and the web application via a clearly drawn interface.
- That user actions in the shop-app (e.g., clicking “buy”) initiate a series of interactions: fetching product details, connecting wallet via MetaMask, and executing a smart contract transaction.
- Admin view fetching data from the blockchain for a list view of purchase history.
- Including a small inset that shows the local development environment, including Hardhat’s local node, for clarity in understanding the development workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Nodes
    U["User"]:::external

    %% Shop App (Frontend)
    subgraph "Shop App (Frontend)"
        subgraph "Pages"
            A["Product Listing Page"]:::frontend
            B["Product Detail Page"]:::frontend
            C["Shopping Cart Page"]:::frontend
            D["Admin Page"]:::frontend
        end
        E["UI Components"]:::frontend
        subgraph "State Management & Hooks"
            F["Cart Store (cartStore.ts)"]:::frontend
            G["Use-Toast Hook (use-toast.ts)"]:::frontend
            H["Blockchain Interaction Hook (useBlockchain.ts)"]:::frontend
        end
        I["External API Integration (sampleData.ts)"]:::frontend
    end

    %% Blockchain Backend
    subgraph "Blockchain Backend"
        J0["Contracts (contracts/)"]:::blockchain
        subgraph "Smart Contracts Modules"
            J1["Lock Contract (Lock.ts)"]:::blockchain
            J2["PurchaseHistory Contract (PurchaseHistory.ts)"]:::blockchain
        end
        K["Hardhat Config"]:::blockchain
        L["Test Suite"]:::blockchain
    end

    %% External Services
    subgraph "External Services"
        M["FakeStore API"]:::external
        N["MetaMask"]:::external
    end

    %% Relationships
    U -->|"views"| A
    A -->|"loads_data"| I
    I -->|"fetches"| M
    H -->|"invokes"| J0
    D -->|"queries"| J0
    H -->|"connects"| N
    N -->|"submits_txn"| J0
    K -->|"deploys"| J0
    L -->|"tests"| J0

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef blockchain fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;

    %% Click Events for Frontend
    click A "https://github.com/koya-tech/simple-shop-dapps/blob/main/shop-app/app/products/page.tsx"
    click B "https://github.com/koya-tech/simple-shop-dapps/blob/main/shop-app/app/products/[id]/page.tsx"
    click C "https://github.com/koya-tech/simple-shop-dapps/blob/main/shop-app/app/cart/page.tsx"
    click D "https://github.com/koya-tech/simple-shop-dapps/blob/main/shop-app/app/admin/page.tsx"
    click E "https://github.com/koya-tech/simple-shop-dapps/tree/main/shop-app/components/"
    click F "https://github.com/koya-tech/simple-shop-dapps/blob/main/shop-app/state/cartStore.ts"
    click G "https://github.com/koya-tech/simple-shop-dapps/blob/main/shop-app/hooks/use-toast.ts"
    click H "https://github.com/koya-tech/simple-shop-dapps/blob/main/shop-app/hooks/useBlockchain.ts"
    click I "https://github.com/koya-tech/simple-shop-dapps/blob/main/shop-app/collections/sampleData.ts"

    %% Click Events for Blockchain Backend
    click J0 "https://github.com/koya-tech/simple-shop-dapps/tree/main/blockchain/contracts/"
    click J1 "https://github.com/koya-tech/simple-shop-dapps/blob/main/blockchain/ignition/modules/Lock.ts"
    click J2 "https://github.com/koya-tech/simple-shop-dapps/blob/main/blockchain/ignition/modules/PurchaseHistory.ts"
    click K "https://github.com/koya-tech/simple-shop-dapps/blob/main/blockchain/hardhat.config.ts"
    click L "https://github.com/koya-tech/simple-shop-dapps/tree/main/blockchain/test/"
```
