How ramanand-tomar/staking-defi-system works
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: App.tsx App shell · web3.ts Web3 adapter · Index.tsx Dashboard · Web3Context.tsx Web3 context
Components 20
Browser UI
React SPA screens, dashboard components, and shared design system
- App boot · Mounts the React application into the browser
src/main.tsx - App shell · Top-level layout and route composition
src/App.tsx - Dashboard · Main staking and rewards experience
src/pages/Index.tsx - Buy page · Token purchase flow
src/pages/Buy.tsx - Demo page · Secondary demonstration screen
src/pages/Demo.tsx - Fallback · Not-found route handler
src/pages/NotFound.tsx - Feature panels · Staking, rewards, buy, stats, history, and owner tools panels
- Wallet UI · Wallet connection control and transaction feedback entry points
src/components/WalletButton.tsx - UI kit · 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 · Global wallet, network, and contract access state
src/contexts/Web3Context.tsx - Staking data · Loads and refreshes live staking metrics from chain
src/hooks/useStakingData.ts - Web3 adapter · Creates provider, signer, and contract bindings
src/lib/web3.ts - Contract ABIs · Data-driven contract interfaces used by the frontend
src/ABI - MetaMask · Signs user transactions and exposes the connected account
- ethers.js · Blockchain client used for reads and writes
On-chain Domain
Smart contracts and blockchain trust boundary
- Sale contract · Handles token purchase and sale pricing
contracts - Staking contract · Manages deposits, withdrawals, and reward claims
contracts - Token contracts · Stake token and reward token used by the app
contracts - Ethereum network · Source of truth for balances, rewards, pricing, and ownership
- Explorer links · Transaction verification happens via external blockchain explorers
Connections 20
- 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