# azzurriii/azzurri-tokens architecture

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

- Interactive diagram: https://gitdiagram.com/azzurriii/azzurri-tokens
- Repository: https://github.com/azzurriii/azzurri-tokens

## Overview

##### Main Components
- Azzurri Token Contract (ERC20) – This is the core token contract incorporating fees, minting logic, and DEX integration.
- NFT Contract – Handles minting, burning, and level management of NFTs.
- NFT Staking Contract – Manages staking and unstaking of NFTs; depends on the NFT contract.
- Token Staking Contract – Manages token staking, rewards distribution, and treasury interactions; depends on the token (and possibly a reward token) contract.
- IDO (Initial DEX Offering) Contract – Governs token sale, vesting schedules, and associated parameters.
- INO (Initial NFT Offering) Contract – Manages the sale of NFTs with random rarity levels and associated configurations.
- Deployment & Testing Infrastructure – Although not a “runtime” component, include the deployment scripts and test framework (Hardhat, scripts, deployments JSON, etc.) to show how contracts are deployed and verified.
- External Dependencies – Include the DEX (router) integration for the token, Chainlink VRF (or similar) considerations for randomness in INO, and any IPFS links (as seen in deployments-ipfs.json).

##### Out the Relationships and Data Flow
- The Azzurri Token contract interacts with the DEX router to establish liquidity pairs upon deployment.
- The Token Staking contract should illustrate an interaction with both the token contract and the treasury management.
- The IDO contract interacts directly with the token for sales, imposing parameters such as purchase limits, vesting schedules, and release configuration.

##### Architectural Patterns & Design Principles
- Modular Design: Each feature (token, NFT, staking, offerings) is encapsulated in its own set of contracts.
- Separation of Concerns: The project cleanly separates business logic (contracts) from deployment logic (scripts) and from testing.
- Dependency Injection: Several contracts reference others (e.g., staking contracts depend on the NFT or token contracts), so make sure to indicate these dependencies.
- External Integrations: Mark external points such as DEX routers for token pairing and potential randomness providers for the INO.

##### Relevant Technologies, Frameworks, or Libraries
- Hardhat – Used for compiling, testing, and deploying the Solidity contracts.
- Solidity – The programming language behind the smart contracts.
- Node.js – The runtime environment for running scripts and tests.
- (Potential) Chainlink or similar for secure randomness, as suggested under security considerations in the README.

## Diagram (Mermaid)

```mermaid
graph TB
  %% Smart Contracts Subgraph
  subgraph "Smart Contracts"
    AToken["Azzurri Token (ERC20)"]:::core
    NFT["NFT Contract"]:::core
    NFTStake["NFT Staking Contract"]:::feature
    TokenStake["Token Staking Contract"]:::feature
    IDO["IDO Contract"]:::feature
    INO["INO Contract"]:::feature
  end

  %% Deployment & Testing Subgraph
  subgraph "Deployment & Testing"
    deployScripts["Deployment Scripts"]:::deploy
    testingInfra["Testing Framework & Config"]:::testing
    tokenDeploy["Azzurri Token Deployment"]:::deploy
    nftDeploy["NFT Deployment"]:::deploy
    nftStakingDeploy["NFT Staking Deployment"]:::deploy
    tokenStakingDeploy["Token Staking Deployment"]:::deploy
    idoDeploy["IDO Deployment"]:::deploy
    inoDeploy["INO Deployment"]:::deploy
    tokenTest["Azzurri Token Test"]:::testing
    nftTest["NFT Test"]:::testing
    nftStakingTest["NFT Staking Test"]:::testing
    tokenStakingTest["Token Staking Test"]:::testing
    idoTest["IDO Test"]:::testing
    inoTest["INO Test"]:::testing
    hardhatCfg["Hardhat Configuration"]:::testing
    ipfsData["IPFS Deployment Data"]:::testing
  end

  %% External Services Subgraph
  subgraph "External Services"
    DEXRouter["DEX Router"]:::external
    RandomnessProvider["Randomness Provider"]:::external
    IPFSService["IPFS"]:::external
  end

  %% Smart Contracts Interactions
  AToken -->|"integratesWith"| DEXRouter
  NFT -->|"dependency"| NFTStake
  NFT -->|"dependency"| INO
  AToken -->|"dependency"| TokenStake
  AToken -->|"dependency"| IDO
  INO -->|"metadataIPFS"| IPFSService
  INO -->|"usesRandomness"| RandomnessProvider

  %% Deployment Scripts relationships to Smart Contracts
  deployScripts --> tokenDeploy
  deployScripts --> nftDeploy
  deployScripts --> nftStakingDeploy
  deployScripts --> tokenStakingDeploy
  deployScripts --> idoDeploy
  deployScripts --> inoDeploy

  tokenDeploy --- AToken
  nftDeploy --- NFT
  nftStakingDeploy --- NFTStake
  tokenStakingDeploy --- TokenStake
  idoDeploy --- IDO
  inoDeploy --- INO

  %% Testing Framework relationships
  testingInfra --> tokenTest
  testingInfra --> nftTest
  testingInfra --> nftStakingTest
  testingInfra --> tokenStakingTest
  testingInfra --> idoTest
  testingInfra --> inoTest
  testingInfra --> hardhatCfg
  testingInfra --> ipfsData

  tokenTest --- AToken
  nftTest --- NFT
  nftStakingTest --- NFTStake
  tokenStakingTest --- TokenStake
  idoTest --- IDO
  inoTest --- INO

  %% Click Events for Smart Contracts
  click AToken "https://github.com/azzurriii/azzurri-tokens/tree/main/contracts/token"
  click NFT "https://github.com/azzurriii/azzurri-tokens/tree/main/contracts/nfts"
  click NFTStake "https://github.com/azzurriii/azzurri-tokens/tree/main/contracts/staking"
  click TokenStake "https://github.com/azzurriii/azzurri-tokens/tree/main/contracts/staking"
  click IDO "https://github.com/azzurriii/azzurri-tokens/tree/main/contracts/sale"
  click INO "https://github.com/azzurriii/azzurri-tokens/tree/main/contracts/sale"

  %% Click Events for Deployment Scripts and Tests
  click tokenDeploy "https://github.com/azzurriii/azzurri-tokens/blob/main/scripts/deploy/01-deploy-token.ts"
  click nftDeploy "https://github.com/azzurriii/azzurri-tokens/blob/main/scripts/deploy/00-deploy-nft.ts"
  click nftStakingDeploy "https://github.com/azzurriii/azzurri-tokens/blob/main/scripts/deploy/02-deploy-nft-staking.ts"
  click idoDeploy "https://github.com/azzurriii/azzurri-tokens/blob/main/scripts/deploy/03-deploy-ido.ts"
  click inoDeploy "https://github.com/azzurriii/azzurri-tokens/blob/main/scripts/deploy/04-deploy-ino.ts"
  click tokenStakingDeploy "https://github.com/azzurriii/azzurri-tokens/blob/main/scripts/deploy/05-deploy-token-staking.ts"

  click tokenTest "https://github.com/azzurriii/azzurri-tokens/blob/main/test/Token.test.ts"
  click nftTest "https://github.com/azzurriii/azzurri-tokens/blob/main/test/NFT.test.ts"
  click nftStakingTest "https://github.com/azzurriii/azzurri-tokens/blob/main/test/NFTStaking.test.ts"
  click idoTest "https://github.com/azzurriii/azzurri-tokens/blob/main/test/IDO.test.ts"
  click inoTest "https://github.com/azzurriii/azzurri-tokens/blob/main/test/INO.test.ts"
  click tokenStakingTest "https://github.com/azzurriii/azzurri-tokens/blob/main/test/TokenStaking.test.ts"

  click testingInfra "https://github.com/azzurriii/azzurri-tokens/tree/main/test/"
  click deployScripts "https://github.com/azzurriii/azzurri-tokens/tree/main/scripts/"
  click hardhatCfg "https://github.com/azzurriii/azzurri-tokens/blob/main/hardhat.config.ts"
  click ipfsData "https://github.com/azzurriii/azzurri-tokens/blob/main/deployments-ipfs.json"

  %% Styles
  classDef core fill:#f9c,stroke:#333,stroke-width:2px;
  classDef feature fill:#ccf,stroke:#333,stroke-width:2px;
  classDef deploy fill:#cfc,stroke:#333,stroke-width:2px;
  classDef testing fill:#fc9,stroke:#333,stroke-width:2px;
  classDef external fill:#cff,stroke:#333,stroke-width:2px;
```
