# ashrafbeshtawi/landlord architecture

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

- Interactive diagram: https://gitdiagram.com/ashrafbeshtawi/landlord
- Repository: https://github.com/ashrafbeshtawi/landlord

## Overview

##### Project type and purpose
- This is a blockchain-enabled full-stack DApp called “LandLordToken (LND)”.
- It consists of:
- A Solidity smart contract (ERC-20 token + profit-claim logic)
- A backend/service layer that signs profit claims (implemented as Next.js API routes)
- A Next.js frontend for users to connect wallets, view balances, and claim tokens
- A local Hardhat node (or any Ethereum‐compatible RPC endpoint) for development/deployment

##### File structure
- Top level:
- docker-compose.yml: orchestrates the Next.js service and a local Hardhat node
- nextjs/: frontend & backend (Next.js app)
- web3/: smart contract source, Hardhat config, deployment scripts, tests
- nextjs/:
- src/app/page.tsx, layout.tsx + components/: UI pages and React components
- src/app/api/balance/route.ts & api/signature/route.ts: backend endpoints
- store/, theme/: client global state and styling
- web3/:
- contracts/: Solidity files (using OpenZeppelin)
- scripts/deploy.js: deploys contracts
- hardhat.config.js: network & compiler settings
- test/: contract unit tests

##### Extract architecture insights from README
- Smart contract flows:
1. Owner calls `distributeProfits(amount)` on the contract
2. Contract records snapshot time & excludes owner
3. Backend computes individual entitlements at snapshot time
4. Backend signs messages (ECDSA) for each claimant
5. User submits signed claim to `claimProfit()`, contract verifies signature & transfers tokens
- Tech stack:
- Solidity 0.8.x, Hardhat, Ethers.js v6, OpenZeppelin
- Next.js (TypeScript), React, Tailwind/CSS

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Roles
    Owner["Owner"]:::external
    HolderUser["Token Holder"]:::external

    %% Orchestration
    DockerCompose["Docker Compose"]:::service

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        UserWallet["User Wallet (MetaMask)"]:::presentation
        NextFrontend["Next.js Frontend"]:::presentation

        Page["page.tsx"]:::presentation
        Layout["layout.tsx"]:::presentation
        CSS["globals.css"]:::presentation

        Hero["HeroSection"]:::presentation
        HolderPanel["HolderPanel"]:::presentation
        NavBar["NavigationBar"]:::presentation
        TeamSection["TeamSection"]:::presentation
        TimelineSection["TimelineSection"]:::presentation
        TokenomicsSection["TokenomiksSection"]:::presentation
        WalletButton["WalletConnectButton"]:::presentation
        WhitepaperSection["WhitepaperSection"]:::presentation
    end

    %% Service Layer
    subgraph "Service Layer (Next.js API)" 
        direction TB
        NextAPI["Next.js API"]:::service
        BalanceEP["/api/balance"]:::service
        SignatureEP["/api/signature"]:::service

        Store["store.ts"]:::service
        Theme["theme.tsx"]:::service
    end

    subgraph "Config & Build" 
        direction TB
        Dockerfile["Dockerfile"]:::service
        NextConfig["next.config.ts"]:::service
        ESLint["eslint.config.mjs"]:::service
        PostCSS["postcss.config.mjs"]:::service
    end

    %% Blockchain Layer
    subgraph "Blockchain Layer" 
        direction TB
        HardhatNode["Hardhat Node (RPC)"]:::blockchain
        Contract["LandLordToken Contract"]:::blockchain
        ContractsDir["contracts/"]:::blockchain
        HardhatConfig["hardhat.config.js"]:::blockchain
        DeployScript["deploy.js"]:::blockchain
        Tests["LandLordToken.test.js"]:::blockchain
    end

    %% Connections
    Owner -->|"use UI"| NextFrontend
    HolderUser -->|"use UI"| NextFrontend

    NextFrontend -->|"GET /api/balance"| BalanceEP
    NextFrontend -->|"POST /api/signature"| SignatureEP

    BalanceEP -->|"eth_call"| HardhatNode
    SignatureEP -->|"eth_call/signMessage"| HardhatNode

    NextFrontend -->|"eth_sendTransaction\n(distributeProfits/claimProfit)"| HardhatNode
    HardhatNode -->|"executes tx\n(emits events)"| Contract

    DockerCompose --> NextFrontend
    DockerCompose --> HardhatNode

    %% Click Events
    click DockerCompose "https://github.com/ashrafbeshtawi/landlord/blob/main/docker-compose.yml"
    click Page "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/app/page.tsx"
    click Layout "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/app/layout.tsx"
    click CSS "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/app/globals.css"
    click Hero "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/components/HeroSection.tsx"
    click HolderPanel "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/components/HolderPanel.tsx"
    click NavBar "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/components/NavigationBar.tsx"
    click TeamSection "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/components/TeamSection.tsx"
    click TimelineSection "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/components/TimelineSection.tsx"
    click TokenomicsSection "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/components/TokenomiksSection.tsx"
    click WalletButton "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/components/WalletConnectButton.tsx"
    click WhitepaperSection "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/components/WhitepaperSection.tsx"
    click BalanceEP "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/app/api/balance/route.ts"
    click SignatureEP "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/app/api/signature/route.ts"
    click Store "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/store/store.ts"
    click Theme "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/src/theme/theme.tsx"
    click Dockerfile "https://github.com/ashrafbeshtawi/landlord/tree/main/nextjs/Dockerfile"
    click NextConfig "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/next.config.ts"
    click ESLint "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/eslint.config.mjs"
    click PostCSS "https://github.com/ashrafbeshtawi/landlord/blob/main/nextjs/postcss.config.mjs"
    click ContractsDir "https://github.com/ashrafbeshtawi/landlord/tree/main/web3/contracts/"
    click HardhatConfig "https://github.com/ashrafbeshtawi/landlord/blob/main/web3/hardhat.config.js"
    click DeployScript "https://github.com/ashrafbeshtawi/landlord/blob/main/web3/scripts/deploy.js"
    click Tests "https://github.com/ashrafbeshtawi/landlord/blob/main/web3/test/LandLordToken.test.js.js"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#004085,color:#004085;
    classDef service fill:#d4edda,stroke:#155724,color:#155724;
    classDef blockchain fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
