mshamba

🌾 Mshamba

Mshamba is a decentralized platform for tokenizing agricultural projects on the Internet Computer Protocol (ICP). It enables urban investors to invest directly in farms, allows landowners to lease unused land, and empowers farmers to raise capital transparently without predatory loans. It also facilitates cooperation across the entire agricultural supply chain.

---

🧠 Project Architecture Overview

The project is structured into modular components, each handling a distinct domain of the system:

---

1. main.mo — Central Controller

• Acts as the orchestrator.
• Connects all modules: profiles, farms, tokens, land, investments.
• Routes API calls from the frontend or other actors.

---

2. profiles.mo — User Identity & Roles

Manages user profiles across all roles:

• Stores: name, email, role, bio, location, joinedAt, wallet address.
• Functions:
  • upsertProfile: create or update your profile.
  • myProfile: view your own profile.
  • getProfileOf: view another user's profile.
  • listUsers: get all registered users.

---

3. farms.mo — Farm Project Management

Handles creation and funding of farms:

• Tracks: farm name, description, owner, funding goal, shares, status, investors.
• Functions:
  • createFarm: farmer posts a project.
  • getFarm: retrieve a specific farm.
  • listFarms: all farms in the system.
  • listFarmsByOwner: farms owned by the caller.
  • investInFarm: fund a farm.

---

4. tokens.mo — Share Ledger (Farm Shares)

Manages ownership of farm shares (similar to stocks):

• Uses a composite key: farmId#Principal.
• Tracks: how many shares a user owns, at what average price.
• Functions:
  • addShares: assign shares to a user.
  • mySharesIn: check shares in a single farm.
  • myAllShares: view all shareholdings.

---

5. land.mo — Land Listings & Leasing

Manages leasing of unused land:

• Stores: location, size, rate per month, availability, owner.
• Functions:
  • registerLand: post a land listing.
  • getLand: view a land post.
  • listAvailableLand: view all leasable land.
  • myLand: view your own listings.
  • markAsLeased: update availability.

---

6. investments.mo — Investment Journal

Logs every funding transaction:

• Tracks: amount, price per share, shares received, timestamp.
• Functions:
  • recordInvestment: log a farm investment.
  • getInvestment: fetch a specific investment.
  • listMyInvestments: view all personal investment records.

---

7. types.mo — Shared Type Definitions

Defines global data types:

• Farm, UserProfile, FarmShare, Investment, LandListing, Role, etc.
• Result<T>: standard way to return success or error.

---

8. utils.mo — Helper Utilities

Defines:

public type Result<T> = {
  #ok: T;
  #err: Text;
};

## Frontend repo:
  https://github.com/VeeThoithi
If you want to start working on your project right away, you might want to try the following commands:

## Valuation Model repo:
  https://github.com/ericx00/Landvaluation
```bash
cd mshamba/
dfx help
dfx canister --help

Running the project locally

If you want to test your project locally, you can use the following commands:

# Starts the replica, running in the background
dfx start --background


# Make sure that you have node
node --version

# Install Frontend Dependencies
npm install --save-dev vite @types/node


# Deploys your canisters to the replica and generates your candid interface
dfx deploy

Once the job completes, your application will be available at http://localhost:4943?canisterId={asset_canister_id}.

If you have made changes to your backend canister, you can generate a new candid interface with

npm run generate

at any time. This is recommended before starting the frontend development server, and will be run automatically any time you run dfx deploy.

If you are making frontend changes, you can start a development server with

npm start

Which will start a server at http://localhost:8080, proxying API requests to the replica at port 4943.

Note on frontend environment variables

If you are hosting frontend code somewhere without using DFX, you may need to make one of the following adjustments to ensure your project does not fetch the root key in production:

• setDFX_NETWORK to ic if you are using Webpack
• use your own preferred method to replace process.env.DFX_NETWORK in the autogenerated declarations
  • Setting canisters -> {asset_canister_id} -> declarations -> env_override to a string in dfx.json will replace process.env.DFX_NETWORK with the string in the autogenerated declarations
• Write your own createActor constructor