# 0x5h31d0n/agriscrow-ton architecture

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

- Interactive diagram: https://gitdiagram.com/0x5h31d0n/agriscrow-ton
- Repository: https://github.com/0x5h31d0n/agriscrow-ton

## Overview

##### Project Type and Purpose
- Agriscrow is a full-stack, blockchain-powered agricultural marketplace.
- It connects four user roles (Farmers, Buyers, Landlords, Renters) via a React/TypeScript frontend, a Flask backend with SQLite, and smart contracts on the TON blockchain.

##### File Structure
- Top-level:
- Frontend/ – React (Vite + Tailwind) code, with components organized by feature (auth, community, marketplace, equipment, dashboard, wallet).
- backend/ – Flask app (`app.py`), CORS, SQLite storage, file uploads.
- contracts/ – Tact / TON smart contracts (`auth.fc`, `escrow` folder).
- Config: ESLint, Tailwind, Vite, Flask requirements.
- Persistence: `backend/users.db`, `backend/uploads/`.
- CI / scripts: none; deployment via Vite build & Flask + Gunicorn.

##### README for Insights
- Confirms architecture: React frontend ↔ Flask API ↔ SQLite + file storage + TON blockchain.
- Highlights: smart-contract escrow, wallet integration (TON Connect), multi-user roles, real-time updates.

a. Main Components
- Clients (Web browser, Mobile browser)
- Frontend SPA (React + Vite + Tailwind)
- Wallet Integration (TON Connect client library)
- Backend API (Flask + Flask-CORS)
- Database (SQLite)
- File Storage (uploads directory)
- Smart Contracts (Tact contracts deployed on TON network)
- External Services (TON Blockchain network, TON Sandbox/Testnet)
- Optional: Real-time layer (if using web sockets or polling)

b. Relationships & Data Flows
1. User interacts with Frontend SPA.
2. SPA calls REST endpoints on Flask API for auth, product listings, community posts, rentals.
3. Flask API reads/writes SQLite and serves uploaded files.
4. For payments/rentals: SPA invokes TON Connect → signs transaction → interacts directly with TON smart contracts.
5. Optional: Flask API may trigger off-chain events based on smart contract state (webhooks or polling).
6. Community and marketplace updates propagate via API → SPA.

c. Architectural Patterns
- Client-Server separation (SPA + REST API)
- Modular frontend by feature (Component-per-domain)
- Monolithic backend (single Flask app)
- Smart-contract layer decoupled from backend (on-chain escrow)
- FCFS order handling in smart contracts
- Single-source-of-truth on-chain for transactions; SQLite for off-chain data

d. Key Technologies
- Frontend: React 18, TypeScript, Vite, Tailwind CSS, TON Connect SDK
- Backend: Flask, Flask-CORS, SQLite, Werkzeug
- Smart Contracts: Tact, TON Core SDK, TON Blockchain
- Dev/Deployment: Node.js, Python 3.8+, Gunicorn/nginx for production

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Web/Mobile Browser"]:::external
        Browser -->|"loads"| ReactSPA["React SPA"]:::frontend

        subgraph "Modules"
            direction TB
            AuthModule["Auth Module"]:::frontend
            CommunityModule["Community Module"]:::frontend
            MarketplaceModule["Marketplace Module"]:::frontend
            EquipmentModule["Equipment/Rentals Module"]:::frontend
            DashboardModule["Dashboard Module"]:::frontend
            SellModule["Sell Module"]:::frontend
            WalletIntegration["Wallet Integration"]:::frontend
            APIService["API Service Layer"]:::frontend
            Config["Configuration"]:::frontend
            ContractBinding["Smart-Contract Bindings"]:::frontend
        end

        ReactSPA --> AuthModule
        ReactSPA --> CommunityModule
        ReactSPA --> MarketplaceModule
        ReactSPA --> EquipmentModule
        ReactSPA --> DashboardModule
        ReactSPA --> SellModule
        ReactSPA --> WalletIntegration
        ReactSPA --> APIService
        ReactSPA --> Config
        ReactSPA --> ContractBinding
    end

    %% Backend & Off-Chain Layer
    subgraph "Off-Chain Layer"
        direction TB
        FlaskAPI["Flask API (backend/app.py)"]:::backend
        SQLiteDB["SQLite DB"]:::backend
        FileStore["File Storage"]:::backend
    end

    APIService -->|"/auth/*, /products/*, etc."| FlaskAPI
    FlaskAPI -->|reads/writes| SQLiteDB
    FlaskAPI -->|serves files| FileStore

    %% On-Chain Layer
    subgraph "On-Chain Layer"
        direction TB
        TONNetwork["TON Blockchain Network"]:::external
        subgraph "Smart Contracts"
            direction TB
            EscrowContract["Escrow Contract"]:::onchain
            MultiSig["Multi-Sig Contract"]:::onchain
            TimeLock["Timelock Contract"]:::onchain
            DisputeResolver["DisputeResolver Contract"]:::onchain
        end
    end

    WalletIntegration -->|"TON Connect SDK"| TONNetwork
    ContractBinding -->|"binds to"| EscrowContract
    TONNetwork --> EscrowContract
    TONNetwork --> MultiSig
    TONNetwork --> TimeLock
    TONNetwork --> DisputeResolver

    %% Click Events
    click ReactSPA "https://github.com/0x5h31d0n/agriscrow-ton/tree/main/Frontend/src"
    click LoginPage "https://github.com/0x5h31d0n/agriscrow-ton/blob/main/Frontend/src/components/auth/LoginPage.tsx"
    click RegisterPage "https://github.com/0x5h31d0n/agriscrow-ton/blob/main/Frontend/src/components/auth/RegisterPage.tsx"
    click AuthModule "https://github.com/0x5h31d0n/agriscrow-ton/tree/main/Frontend/src/components/auth"
    click CommunityModule "https://github.com/0x5h31d0n/agriscrow-ton/tree/main/Frontend/src/components/community"
    click MarketplaceModule "https://github.com/0x5h31d0n/agriscrow-ton/tree/main/Frontend/src/components/marketplace"
    click EquipmentModule "https://github.com/0x5h31d0n/agriscrow-ton/blob/main/Frontend/src/components/equipment/RentalPage.tsx"
    click DashboardModule "https://github.com/0x5h31d0n/agriscrow-ton/tree/main/Frontend/src/components/dashboard"
    click SellModule "https://github.com/0x5h31d0n/agriscrow-ton/blob/main/Frontend/src/components/sell/SellPage.tsx"
    click WalletIntegration "https://github.com/0x5h31d0n/agriscrow-ton/tree/main/Frontend/src/components/wallet"
    click APIService "https://github.com/0x5h31d0n/agriscrow-ton/blob/main/Frontend/src/services/authService.ts"
    click Config "https://github.com/0x5h31d0n/agriscrow-ton/blob/main/Frontend/src/config/api.config.ts"
    click ContractBinding "https://github.com/0x5h31d0n/agriscrow-ton/blob/main/Frontend/src/contracts/auth.contract.ts"
    click FlaskAPI "https://github.com/0x5h31d0n/agriscrow-ton/blob/main/backend/app.py"
    click SQLiteDB "https://github.com/0x5h31d0n/agriscrow-ton/blob/main/backend/users.db"
    click FileStore "https://github.com/0x5h31d0n/agriscrow-ton/tree/main/backend/uploads/"
    click EscrowContract "https://github.com/0x5h31d0n/agriscrow-ton/blob/main/contracts/auth.fc"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef onchain fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
