# ramanand-tomar/staking-defi-system architecture

> Architecture diagram of the GitHub repository ramanand-tomar/staking-defi-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ramanand-tomar/staking-defi-system
- Repository: https://github.com/ramanand-tomar/staking-defi-system

## Overview

1. **Project shape**
   - StakeFlow is a single-page React frontend that talks directly to Ethereum-compatible smart contracts.
   - There is no traditional backend in the repository; the blockchain is the source of truth for balances, staking state, rewards, and sale pricing.

2. **Core runtime boundary**
   - The app runs in the browser via Vite + React 18 + TypeScript.
   - The main execution boundary is between the UI and the wallet/blockchain layer: users interact in the browser, MetaMask signs transactions, and `ethers.js` sends reads/writes to contracts.

3. **Application shell and routing**
   - `src/main.tsx` boots the app and mounts `App.tsx`.
   - `src/pages` contains the route-level screens: main dashboard (`Index.tsx`), token purchase flow (`Buy.tsx`), a demo page (`Demo.tsx`), and a fallback (`NotFound.tsx`).
   - The repo looks like a small routed SPA rather than a multi-service system.

4. **Wallet and web3 state**
   - `src/contexts/Web3Context.tsx` is the main global boundary for wallet connection, network state, and contract access.
   - `src/lib/web3.ts` is the low-level integration layer that likely creates the provider/signer/contracts using `ethers.js`.
   - `src/ABI/*.json` stores the contract ABIs consumed by the frontend, so contract wiring is data-driven rather than hardcoded in UI components.

5. **Contract-facing business flows**
   - The application centers on four on-chain contracts referenced in the README: token sale, staking engine, stake token, and reward token.
   - The buy flow talks to the sale contract to exchange native currency for STK.
   - The staking flow talks to the staking contract to deposit STK, withdraw stake, and claim reward tokens.
   - Owner/admin tools in the UI map to privileged contract methods like withdrawing sale proceeds or updating token pricing.

6. **State and polling**
   - `src/hooks/useStakingData.ts` is the main data hook for loading live staking metrics and likely refreshing them over time.
   - This creates a read-heavy data flow from chain → hook → panels/cards, while user actions go from UI → wallet approval → transaction → chain → refreshed state.
   - The README’s “live rewards counter” implies periodic updates rather than server push.

7. **Primary UI composition**
   - The dashboard is assembled from focused feature components in `src/components`: staking, rewards, buy panel, live counter, APY calculator, stats card, transaction history, wallet button, and owner tools.
   - `App.tsx` and the page components likely compose these into the visible layout and coordinate which sections appear by route and wallet role.

8. **Transaction and verification path**
   - User actions such as buy, stake, claim, and withdraw are initiated in UI components, signed in MetaMask, executed on-chain, then reflected back into the app through refreshed reads.
   - `TransactionHistory.tsx` provides the audit trail UI, and the README indicates transaction links point to external blockchain explorers, so verification happens outside the app.

9. **Design system and shared UI**
   - `src/components/ui/*` is a large shadcn/ui-style component library used for consistent controls, dialogs, tables, cards, tabs, and toasts.
   - This is presentation infrastructure, not business logic, and it supports the app’s dark, dashboard-oriented interface.

10. **Styling and frontend tooling**
   - Tailwind CSS and PostCSS drive styling; `src/App.css` and `src/index.css` hold app-level styles.
   - Vite, TypeScript, ESLint, and the Tailwind config define the build and developer tooling boundary.
   - `public/robots.txt` and the static `public` assets indicate a deployable frontend artifact with no server-side rendering layer.

11. **External dependencies that matter architecturally**
   - MetaMask is the primary user wallet/provider.
   - `ethers.js` is the blockchain adapter.
   - TanStack Query and Sonner are used for async data freshness and user feedback/toasts, which are important because on-chain operations are slow and failure-prone.

12. **Contracts as a separate trust domain**
   - The `contracts` directory and Solidity references in the README represent the separate on-chain trust boundary.
   - The frontend is only a client; authoritative staking balances, reward accrual, token sale pricing, and ownership checks live in the contracts, not in the app state.

13. **Likely architecture diagram framing**
   - Draw three main zones: browser UI, web3 integration layer, and blockchain/contracts.
   - Show the UI pages/components feeding into a shared Web3 context and staking data hook.
   - Show the web3 layer reading ABIs and talking through MetaMask/ethers.js to the four contracts.
   - Show external explorer links and wallet notifications as side channels from the UI rather than separate services.

Main entry points: [`src/App.tsx`](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/App.tsx) (App shell), [`src/lib/web3.ts`](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/lib/web3.ts) (Web3 adapter), [`src/pages/Index.tsx`](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/pages/Index.tsx) (Dashboard), [`src/contexts/Web3Context.tsx`](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/contexts/Web3Context.tsx) (Web3 context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_ui["Browser UI"]
  node_node_main["App boot<br/>Vite entry<br/>[main.tsx]"]
  node_node_app["App shell<br/>React shell<br/>[App.tsx]"]
  node_node_index["Dashboard<br/>Route page<br/>[Index.tsx]"]
  node_node_buy["Buy page<br/>Route page<br/>[Buy.tsx]"]
  node_node_demo["Demo page<br/>Route page<br/>[Demo.tsx]"]
  node_node_404["Fallback<br/>Route page<br/>[NotFound.tsx]"]
  node_node_panels["Feature panels<br/>Dashboard components"]
  node_node_wallet_ui["Wallet UI<br/>UI component<br/>[WalletButton.tsx]"]
  node_node_shadcn["UI kit<br/>Component library"]
end

subgraph group_grp_web3["Web3 Layer"]
  node_node_context["Web3 context<br/>React context<br/>[Web3Context.tsx]"]
  node_node_hook["Staking data<br/>React hook<br/>[useStakingData.ts]"]
  node_node_web3["Web3 adapter<br/>ethers layer<br/>[web3.ts]"]
  node_node_abis["Contract ABIs<br/>ABI bundle"]
  node_node_metamask{{"MetaMask<br/>wallet provider"}}
  node_node_ethers["ethers.js"]
end

subgraph group_grp_chain["On-chain Domain"]
  node_node_sale[("Sale contract<br/>smart contract")]
  node_node_staking[("Staking contract<br/>smart contract")]
  node_node_tokens[("Token contracts<br/>smart contracts")]
  node_node_chain{{"Ethereum network<br/>blockchain"}}
  node_node_explorer["Explorer links<br/>external service"]
end

node_node_main -->|"bootstraps"| node_node_app
node_node_app -->|"routes to"| node_node_index
node_node_app -->|"routes to"| node_node_buy
node_node_app -->|"routes to"| node_node_demo
node_node_app -->|"routes to"| node_node_404
node_node_index -->|"composes"| node_node_panels
node_node_index -->|"shows"| node_node_wallet_ui
node_node_panels -->|"reads live data"| node_node_hook
node_node_panels -->|"uses state"| node_node_context
node_node_context -->|"delegates to"| node_node_web3
node_node_web3 -->|"loads interfaces"| node_node_abis
node_node_web3 -->|"uses"| node_node_ethers
node_node_context -->|"connects through"| node_node_metamask
node_node_web3 -->|"reads and writes"| node_node_chain
node_node_buy -->|"buys from"| node_node_sale
node_node_panels -->|"stakes and claims"| node_node_staking
node_node_panels -->|"uses tokens"| node_node_tokens
node_node_panels -->|"verifies txs"| node_node_explorer
node_node_shadcn -.->|"supports UI"| node_node_panels
node_node_shadcn -.->|"supports UI"| node_node_wallet_ui

click node_node_main "https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/main.tsx"
click node_node_app "https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/App.tsx"
click node_node_index "https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/pages/Index.tsx"
click node_node_buy "https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/pages/Buy.tsx"
click node_node_demo "https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/pages/Demo.tsx"
click node_node_404 "https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/pages/NotFound.tsx"
click node_node_wallet_ui "https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/components/WalletButton.tsx"
click node_node_shadcn "https://github.com/ramanand-tomar/staking-defi-system/tree/main/src/components/ui"
click node_node_context "https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/contexts/Web3Context.tsx"
click node_node_hook "https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/hooks/useStakingData.ts"
click node_node_web3 "https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/lib/web3.ts"
click node_node_abis "https://github.com/ramanand-tomar/staking-defi-system/tree/main/src/ABI"
click node_node_sale "https://github.com/ramanand-tomar/staking-defi-system/tree/main/contracts"
click node_node_staking "https://github.com/ramanand-tomar/staking-defi-system/tree/main/contracts"
click node_node_tokens "https://github.com/ramanand-tomar/staking-defi-system/tree/main/contracts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_app,node_node_index,node_node_buy,node_node_demo,node_node_404,node_node_panels,node_node_wallet_ui,node_node_shadcn toneBlue
class node_node_context,node_node_hook,node_node_web3,node_node_abis,node_node_metamask,node_node_ethers toneAmber
class node_node_sale,node_node_staking,node_node_tokens,node_node_chain,node_node_explorer toneMint
```

## Components

### Browser UI

React SPA screens, dashboard components, and shared design system

- [App boot](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/main.tsx): Vite entry · Mounts the React application into the browser · `src/main.tsx`
- [App shell](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/App.tsx): React shell · Top-level layout and route composition · `src/App.tsx`
- [Dashboard](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/pages/Index.tsx): Route page · Main staking and rewards experience · `src/pages/Index.tsx`
- [Buy page](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/pages/Buy.tsx): Route page · Token purchase flow · `src/pages/Buy.tsx`
- [Demo page](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/pages/Demo.tsx): Route page · Secondary demonstration screen · `src/pages/Demo.tsx`
- [Fallback](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/pages/NotFound.tsx): Route page · Not-found route handler · `src/pages/NotFound.tsx`
- **Feature panels**: Dashboard components · Staking, rewards, buy, stats, history, and owner tools panels
- [Wallet UI](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/components/WalletButton.tsx): UI component · Wallet connection control and transaction feedback entry points · `src/components/WalletButton.tsx`
- [UI kit](https://github.com/ramanand-tomar/staking-defi-system/tree/main/src/components/ui): Component library · Shared shadcn-style controls, dialogs, tables, tabs, and toasts · `src/components/ui`

### Web3 Layer

Wallet state, contract wiring, and chain-facing data flow

- [Web3 context](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/contexts/Web3Context.tsx): React context · Global wallet, network, and contract access state · `src/contexts/Web3Context.tsx`
- [Staking data](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/hooks/useStakingData.ts): React hook · Loads and refreshes live staking metrics from chain · `src/hooks/useStakingData.ts`
- [Web3 adapter](https://github.com/ramanand-tomar/staking-defi-system/blob/main/src/lib/web3.ts): ethers layer · Creates provider, signer, and contract bindings · `src/lib/web3.ts`
- [Contract ABIs](https://github.com/ramanand-tomar/staking-defi-system/tree/main/src/ABI): ABI bundle · Data-driven contract interfaces used by the frontend · `src/ABI`
- **MetaMask**: wallet provider · Signs user transactions and exposes the connected account
- **ethers.js**: library · Blockchain client used for reads and writes

### On-chain Domain

Smart contracts and blockchain trust boundary

- [Sale contract](https://github.com/ramanand-tomar/staking-defi-system/tree/main/contracts): smart contract · Handles token purchase and sale pricing · `contracts`
- [Staking contract](https://github.com/ramanand-tomar/staking-defi-system/tree/main/contracts): smart contract · Manages deposits, withdrawals, and reward claims · `contracts`
- [Token contracts](https://github.com/ramanand-tomar/staking-defi-system/tree/main/contracts): smart contracts · Stake token and reward token used by the app · `contracts`
- **Ethereum network**: blockchain · Source of truth for balances, rewards, pricing, and ownership
- **Explorer links**: external service · Transaction verification happens via external blockchain explorers

## Connections

- App boot → App shell: bootstraps · Entry point mounts the top-level React app
- App shell → Dashboard: routes to · Primary dashboard screen
- App shell → Buy page: routes to · Purchase flow screen
- App shell → Demo page: routes to · Demo screen
- App shell → Fallback: routes to · Fallback route
- Dashboard → Feature panels: composes · Dashboard assembles feature panels
- Dashboard → Wallet UI: shows · Wallet connect and status controls
- Feature panels → Staking data: reads live data · Panels consume refreshed staking metrics
- Feature panels → Web3 context: uses state · Feature actions depend on shared web3 state
- Web3 context → Web3 adapter: delegates to · Context uses low-level web3 integration
- Web3 adapter → Contract ABIs: loads interfaces · Contract wiring is driven by ABI JSON files
- Web3 adapter → ethers.js: uses · Blockchain reads and writes go through ethers.js
- Web3 context → MetaMask: connects through · Wallet connection and signing happen via MetaMask
- Web3 adapter → Ethereum network: reads and writes · All contract interaction targets the blockchain
- Buy page → Sale contract: buys from · Token purchase flow interacts with sale contract
- Feature panels → Staking contract: stakes and claims · Staking, rewards, and withdrawal actions target staking contract
- Feature panels → Token contracts: uses tokens · Stake and reward token contracts are part of the flow
- Feature panels → Explorer links: verifies txs · Transaction history links out for chain verification
- UI kit → Feature panels: supports UI · Shared presentation components underpin the dashboard
- UI kit → Wallet UI: supports UI · Common controls and toasts support wallet actions
