Domain Model
Purpose
This document defines the core entities, relationships, and domain concepts for the Farmer1st platform.
Current State
Overview
The Farmer1st platform manages complex relationships across agricultural value chains, connecting farmers to cooperatives, brands, factories, and other stakeholders.
┌─────────────────────────────────────────────────────────────────────────────┐
│ DOMAIN MODEL OVERVIEW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ │
│ │ BRAND │ │
│ │(Nestlé, │ │
│ │ Mars) │ │
│ └────┬────┘ │
│ │ │
│ sources_from / owns │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌───────────┐ ┌─────────┐ │
│ │ FACTORY │ │COOPERATIVE│ │ AGENT │ │
│ │ │ │ │ │ │ │
│ └─────────┘ └─────┬─────┘ └────┬────┘ │
│ │ │ │
│ member_of manages │
│ │ │ │
│ ┌─────────────┴──────────────┘ │
│ ▼ │
│ ┌─────────┐ │
│ │ FARMER │◄────────► FAMILY │
│ │ (User) │ │
│ └────┬────┘ │
│ │ │
│ owns │
│ │ │
│ ▼ │
│ ┌─────────┐ │
│ │ FARM │ │
│ │ │ │
│ └─────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Entity Definitions
Users
Users are individuals who interact with the platform. A single person may have multiple roles across different entities.
| User Type | Description | Primary Interface |
|---|---|---|
| Farmer | Agricultural producer, owns/operates farms | PWA (Mobile) |
| Cooperative Member | Works within a cooperative | PWA / Portal |
| Cooperative Admin | Manages cooperative operations | Portal |
| Agent | Field representative, manages multiple farmers | PWA / Portal |
| Brand Employee | Works for a brand (Nestlé, Mars, etc.) | Portal |
| Factory Manager | Manages factory operations | Portal |
| Factory Worker | Operates within factory | Portal |
Note: This list is not exhaustive and will evolve.
Core Entities
| Entity | Description | Key Attributes (TBD) |
|---|---|---|
| Farm | Agricultural production unit | Location, size, crops, certifications |
| Family | Household unit (farmers are part of families) | Members, head of household |
| Cooperative | Farmer organization/collective | Members, leadership, contracts |
| Brand | Large buyer/company (Nestlé, Mars, etc.) | Employees, sourcing relationships |
| Factory | Processing facility | Location, capacity, owner |
| Agent | Field representative entity | Assigned farmers/areas |
Note: Entity list will expand as domain is refined.
Relationships
User-to-Entity Relationships
| Relationship | From | To | Description |
|---|---|---|---|
owner |
User | Farm | Farmer owns a farm |
head_of |
User | Family | Head of household |
member_of |
User | Family | Family member |
member_of |
User | Cooperative | Farmer is coop member |
admin_of |
User | Cooperative | Coop administrator |
employee_of |
User | Brand | Works for brand |
manager_of |
User | Factory | Manages factory |
manages |
User (Agent) | Farm/Farmer | Agent oversight |
Entity-to-Entity Relationships
| Relationship | From | To | Description |
|---|---|---|---|
sources_from |
Brand | Cooperative | Brand sources from coop |
sources_from |
Brand | Farm | Direct farmer relationship |
supplies_to |
Cooperative | Brand | Coop supplies brand |
supplies_to |
Cooperative | Factory | Coop supplies factory |
owned_by |
Factory | Brand | Brand owns factory |
affiliated_with |
Cooperative | Cooperative | Coop networks |
Access Implications
Relationships determine data access (managed by OpenFGA):
Example: Nestlé employee viewing farm data
Brand:Nestle ──sources_from──► Cooperative:CoopA
│
member_of
│
User:FarmerBob ──owns──► Farm:Farm123
Result: Nestlé employee can view Farm123 data (via relationship chain)
Value Chains
Value chains represent commodity types processed through the platform.
| Value Chain | Status | Notes |
|---|---|---|
| Cocoa | Initial | First priority |
| Coffee | Initial | First priority |
| Rubber | Future | Planned |
| Palm Oil | Future | Planned |
| Nuts | Future | Planned |
Value Chain Implementation
Value chains are not part of the authorization model (OpenFGA). Instead:
- Feature flags (Unleash): Control which value chains are enabled per tenant/region
- Data attributes: Farms/products tagged with value chain type
- UI filtering: Portals show relevant value chain data
┌─────────────────────────────────────────────────────────────────────────────┐
│ VALUE CHAIN IMPLEMENTATION │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Feature Flags (Unleash) Data Model │
│ ─────────────────────── ────────── │
│ │
│ value_chain.cocoa: ON Farm │
│ value_chain.coffee: ON └── crops: [cocoa, coffee] │
│ value_chain.rubber: OFF │
│ value_chain.palm_oil: OFF Product │
│ └── value_chain: cocoa │
│ │
│ Controls: Used for: │
│ • Feature availability • Data filtering │
│ • UI visibility • Reporting │
│ • Regional rollout • Traceability │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Scale Considerations
| Metric | Target Scale | Notes |
|---|---|---|
| Total Users | 100 Million | Majority are farmers |
| Farms | ~50-100 Million | 1-2 farms per farmer avg |
| Cooperatives | Thousands | Varies by region |
| Brands | Hundreds | Major commodity buyers |
| Factories | Thousands | Processing facilities |
Multi-Tenancy Considerations
Currently: Single shared platform for all users.
Future consideration: Premium SaaS offering for brands.
| Model | Description | Status |
|---|---|---|
| Shared Platform | All data in shared infrastructure | Current |
| Brand SaaS | Dedicated instance for brand (e.g., Nestlé) | Future/TBD |
See 99-ideas.md for SaaS offering notes.
Open Questions
- Complete list of entity types?
- Complete list of relationship types?
- Detailed attributes per entity?
- Hierarchical relationships (coop of coops)?
- Temporal relationships (seasonal contracts)?
- Geographic/regional modeling?
- Product/harvest/shipment entities?
- Certification and compliance entities?
Dependencies
- OpenFGA for relationship-based access control (see
08-authorization-architecture.md) - Unleash for value chain feature flags
- PostgreSQL for entity storage
Last Updated: 2025-12-25