> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ownafarm.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# System architecture

> A breakdown of the frontend, backend, and Mantle blockchain layers that power OwnaFarm's gamified invoice financing platform end to end.

OwnaFarm consists of three layers: frontend, backend, and blockchain.

```mermaid theme={null}
graph TB
    subgraph Frontend
        FP[Farmer Portal<br/>Next.js :3000]
        IA[Investor App<br/>Next.js :3001]
    end

    subgraph Backend
        API[Go + Gin :8080]
        DB[(PostgreSQL)]
        CACHE[(Valkey)]
        S3[Cloudflare R2]
    end

    subgraph Blockchain
        NFT[OwnaFarmNFT]
        GOLD[GoldToken]
        VAULT[Vault]
        FAUCET[Faucet]
        MNT[Mantle Network]
    end

    FP --> API
    IA --> API
    IA --> MNT

    API --> DB
    API --> CACHE
    API --> S3
    API --> MNT

    NFT --> MNT
    GOLD --> MNT
    VAULT --> MNT
    FAUCET --> MNT
```

## Frontend layer

### Farmer portal

| Route            | Function                       |
| ---------------- | ------------------------------ |
| `/`              | Landing page                   |
| `/register-farm` | Multi-step farmer registration |
| `/admin`         | Invoice management             |

### Investor app

| Route          | Function                   |
| -------------- | -------------------------- |
| `/`            | Homepage with active crops |
| `/shop`        | Seed marketplace           |
| `/farm`        | Personal garden view       |
| `/leaderboard` | Investor rankings          |
| `/profile`     | User stats                 |

## Backend layer

### Responsibilities

| Area             | Function                      |
| ---------------- | ----------------------------- |
| User management  | Profiles, authentication, KYC |
| Game state       | XP, levels, water points      |
| Document storage | Farmer documents to R2        |
| Event indexing   | Sync blockchain events        |

### Data stores

| Store         | Purpose              |
| ------------- | -------------------- |
| PostgreSQL    | Primary database     |
| Valkey        | Caching and sessions |
| Cloudflare R2 | Document storage     |

## Blockchain layer

### Smart contracts

| Contract      | Standard | Purpose              |
| ------------- | -------- | -------------------- |
| GoldToken     | ERC-20   | Platform currency    |
| GoldFaucet    | —        | Testnet distribution |
| OwnaFarmNFT   | ERC-1155 | Invoice tokens       |
| OwnaFarmVault | —        | Yield reserve        |

### Why Mantle

| Feature        | Benefit             |
| -------------- | ------------------- |
| Layer 2        | Low gas fees        |
| EVM compatible | Standard tooling    |
| Fast finality  | Quick confirmations |

## Data distribution

| Data type       | Location      | Reason               |
| --------------- | ------------- | -------------------- |
| Financial state | Blockchain    | Immutable, trustless |
| User identity   | Database      | Privacy, compliance  |
| Game mechanics  | Database      | Flexibility          |
| Documents       | Cloud storage | Size, access         |

## Communication patterns

<CodeGroup>
  ```http Frontend to backend theme={null}
  REST API (JSON)
  POST /api/farmers/register
  GET  /api/user/profile
  POST /api/game/water
  ```

  ```http Frontend to blockchain theme={null}
  WAGMI/Viem (RPC)
  READ:  getAvailableInvoices()
  WRITE: invest(), harvest()
  ```

  ```http Backend to blockchain theme={null}
  go-ethereum (RPC)
  Event listening
  Transaction submission
  ```
</CodeGroup>