# albertobas/olive-oil-trust architecture

> Architecture diagram of the GitHub repository albertobas/olive-oil-trust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/albertobas/olive-oil-trust
- Repository: https://github.com/albertobas/olive-oil-trust

## Overview

##### Main Components
- Smart Contracts (Backend Blockchain Layer):
– Located in “hardhat-env/contracts” along with deployment scripts, Hardhat tasks, and tests.
– These contracts implement the supply chain roles (olive growers, oil mills, distributors, etc.), escrow mechanisms, certificate management, and token minting/trading.
– They are upgradeable (UUPS compliant) which is an important architectural nuance.

- Front-End Application (User Interface Layer):
– Found under “next-app” with a Next.js framework that handles both exploration (public view) and management (authenticated member actions).
– Uses Redux for global state management (hexagonal architecture pattern with the domain core separate from infrastructure).

- Supporting Services:

##### Relationships and Interactions
- The blockchain (Hardhat node) hosts the smart contracts, and deployment scripts in “hardhat-env/scripts” deploy these contracts.

##### Important Architectural Patterns & Design Principles
- Hexagonal Architecture (Ports and Adapters):

- Upgradeable Smart Contracts:
– The contracts use ownership, roles, and UUPS patterns to allow upgrades while preserving state.

- Event-Driven Data Flow:

- Test-Driven Development:
– A rich set of tests (using Mocha, Chai, and Hardhat plugins) ensures the correctness of each component in the blockchain layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Blockchain Layer: Smart Contracts
    subgraph "Blockchain Layer (Smart Contracts)"
        SC1["Contracts (Upgradeable UUPS)"]:::contracts
        SC2["Deployment Scripts"]:::scripts
        SC3["Tasks"]:::tasks
        SC4["Tests (TDD)"]:::tests
    end

    %% Front-End Application (Next.js)
    subgraph "Front-End Application (Next.js)"
        FE1["Explore (Public View)"]:::frontend
        FE2["Management (Authenticated)"]:::frontend
        FE3["Shared UI/State (Redux)"]:::frontend
    end

    %% Data Indexing Layer: Subgraph & GraphQL API
    subgraph "Data Indexing Layer (Subgraph & GraphQL API)"
        SG1["Mappings (AssemblyScript)"]:::subgraphStyle
        SG2["GraphQL API & Entities"]:::subgraphStyle
    end

    %% Supporting Services
    subgraph "Supporting Services"
        SV1["Graph Node (Docker)"]:::services
        SV2["PostgreSQL (Docker)"]:::services
        SV3["IPFS (Docker)"]:::services
    end

    %% External Interaction
    EX["User (MetaMask)"]:::external

    %% Data Flows and Interactions
    SC2 -->|"deploys"| SC1
    SC1 -->|"emitEvents"| SG1
    SC2 -->|"syncState"| SG1
    SG2 -->|"servesData"| FE1
    SG2 -->|"servesData"| FE2
    SC2 -->|"sharesArtifact"| FE3
    EX -->|"sendsTxn"| SC1

    %% Supporting Services Dependencies for Subgraph
    SV1 --> SG1
    SV2 --> SG1
    SV3 --> SG1

    %% Styles
    classDef contracts fill:#ffcc80,stroke:#e65100,stroke-width:2px;
    classDef scripts fill:#ffe0b2,stroke:#ff9800,stroke-width:2px;
    classDef tasks fill:#ffcc80,stroke:#e65100,stroke-width:2px;
    classDef tests fill:#ffcc80,stroke:#e65100,stroke-width:2px;
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef subgraphStyle fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef services fill:#d1c4e9,stroke:#512da8,stroke-width:2px;
    classDef external fill:#f8bbd0,stroke:#c2185b,stroke-width:2px;

    %% Click Events for Component Mapping
    click SC1 "https://github.com/albertobas/olive-oil-trust/tree/main/hardhat-env/contracts"
    click SC2 "https://github.com/albertobas/olive-oil-trust/tree/main/hardhat-env/scripts"
    click SC3 "https://github.com/albertobas/olive-oil-trust/tree/main/hardhat-env/tasks"
    click SC4 "https://github.com/albertobas/olive-oil-trust/tree/main/hardhat-env/test"
    click FE1 "https://github.com/albertobas/olive-oil-trust/tree/main/next-app"
    click FE2 "https://github.com/albertobas/olive-oil-trust/tree/main/next-app"
    click FE3 "https://github.com/albertobas/olive-oil-trust/tree/main/next-app"
    click SG1 "https://github.com/albertobas/olive-oil-trust/tree/main/subgraph/src/mappings"
    click SG2 "https://github.com/albertobas/olive-oil-trust/blob/main/subgraph/schema.graphql"
    click SV1 "https://github.com/albertobas/olive-oil-trust/tree/main/services"
    click SV2 "https://github.com/albertobas/olive-oil-trust/tree/main/services"
    click SV3 "https://github.com/albertobas/olive-oil-trust/tree/main/services"
```
