An open-source, blockchain-backed system that digitizes agricultural supply chains — connecting farmers, cooperatives, processors, and buyers with full transparency, quality assurance, and fair pricing. Funded by BMZ and implemented by GIZ.
This is the INATrace meta repository — the central hub for project-wide documentation, governance, technical specifications, and cross-repo coordination.
Source code lives in the four dedicated component repositories (listed below). This repo is the canonical home for everything that spans the full project:
| What lives here | Purpose |
|---|---|
| 📋 Project charter & governance | Decision-making processes, roles, contribution policies |
| 📐 Technical specs & proposals | Architecture decisions, integration designs, enhancement proposals |
| 🔗 Integration documentation | Cross-system specs (e.g., Asset Registry, EUDR/Whisp, AgStack ecosystem) |
| 🗺️ Roadmap & planning | Project-wide priorities, phased roadmaps, task breakdowns |
| 📖 Landing page & overview | This README — the single entry point for understanding INATrace |
| 🤝 Contributing guide | How to get involved across all INATrace repos |
agstack/inatrace/ ← You are here
│
├── README.md ← Project landing page (this file)
├── ASSET_REGISTRY_INTEGRATION.md ← AgStack Asset Registry integration spec & roadmap
├── CONTRIBUTING.md ← (planned) Cross-repo contribution guide
├── CHARTER.md ← (planned) Project charter
├── GOVERNANCE.md ← (planned) Decision-making & roles
│
├── specs/ ← (planned) Technical specs & enhancement proposals
│ ├── 001-asset-registry-v2.md
│ ├── 002-eudr-compliance.md
│ └── ...
│
├── decisions/ ← (planned) Architecture Decision Records (ADRs)
│ ├── 001-meta-repo-structure.md
│ └── ...
│
└── .github/ ← Issue/PR templates for cross-repo concerns
Design intent: Any document that applies to INATrace as a whole — not just one component — belongs here. Code changes go in the component repos. Project-level decisions, specs, governance, and roadmaps go here.
INATrace is an end-to-end digital traceability platform for agricultural commodities (coffee, cocoa, and beyond). It provides:
- 🔗 Full supply chain transparency — trace every step from smallholder farm to final buyer
- ⛓️ Blockchain-backed trust — immutable records on Hyperledger Fabric
- 🏢 Multi-tenant, multi-value-chain — one system for multiple organizations and commodity types
- 📱 Mobile-first field data — GPS polygon mapping, offline-capable farmer registration
- 📊 Quality & compliance — assure quality standards and support EU Deforestation Regulation (EUDR) compliance
- 💰 Fair pricing — transparent pricing and payment tracking for smallholder farmers
INATrace enhances the economic conditions of smallholder farmers by improving traceability of global supply chains.
┌─────────────────────────────────────────────────────────────────────┐
│ INATrace Platform │
├──────────────┬──────────────┬─────────────────┬────────────────────┤
│ │ │ │ │
│ 📱 Mobile │ 🖥️ Frontend │ ⚙️ Backend │ ⛓️ Blockchain │
│ App │ (Angular) │ (Java/Spring) │ (Hyperledger) │
│ │ │ │ │
│ React Native │ TypeScript │ Java 17 │ Fabric Network │
│ Expo │ Angular 10+ │ Spring Boot │ Chaincode (Go) │
│ MapBox │ │ MySQL 8.4 │ CouchDB │
│ │ │ REST API │ │
├──────────────┴──────────────┴─────────────────┴────────────────────┤
│ │
│ 🗄️ MySQL Database 📧 Email (SMTP) 🗺️ MapBox 💱 Exchange API │
│ │
│ 🌐 AgStack Asset Registry (GeoID) 🛰️ Whisp/EUDR (Compliance) │
└─────────────────────────────────────────────────────────────────────┘
Source code lives in four dedicated repositories. Each has its own README with setup instructions, development guide, and component-specific docs.
⚙️ inatrace-backend — Java API Server
The core API server powering INATrace. Handles user management, product configuration, supply chain operations, processing actions, payments, and integrations.
| Stack | Java 17, Spring Boot, Maven, MySQL 8.4 |
| License | MPL-2.0 |
| Last Updated | 2025-12-24 |
| Top Maintainers | @pece-a (495 commits), @RebernikNejc (126), @MusicDin (96) |
Quick Start:
git clone https://github.com/agstack/inatrace-backend.git
# Set up MySQL via Docker:
docker run --name inatrace-mysql -e MYSQL_ROOT_PASSWORD=root \
-e MYSQL_DATABASE=inatrace -e MYSQL_USER=inatrace \
-e MYSQL_PASSWORD=inatrace -p 3306:3306 -d mysql:8.4.6
# Configure application.properties, then run INATraceBackendApplication.java🖥️ inatrace-frontend — Angular Web Application
The web-based user interface for managing products, companies, value chains, stakeholders, processing, orders, and payments.
| Stack | Angular 10+, TypeScript, Node 14 |
| License | MPL-2.0 |
| Last Updated | 2025-12-24 |
| Top Maintainers | @pece-a (987 commits), @RebernikNejc (175), @borce-paspalovski (145) |
Quick Start:
git clone https://github.com/agstack/inatrace-frontend.git
cd inatrace-frontend
npm install
# Configure environment, then:
ng serve📱 inatrace-mobile — React Native Mobile App
The field-level mobile app for cooperatives and farmers — GPS polygon mapping, farmer registration, offline data collection, and synchronization.
| Stack | React Native, Expo, TypeScript, MapBox |
| Platforms | Android (Google Play) · iOS (App Store) |
| License | MPL-2.0 |
| Last Updated | 2025-12-24 |
| Top Maintainers | @pinokokol (120 commits), @pece-a (9) |
Key Features:
- 📍 Polygon Mapping — GPS-based field boundary capture
- 👨🌾 Farmer Profiles — Detailed cooperative member records
- 📴 Offline Mode — Full functionality without connectivity, auto-sync when online
Quick Start:
git clone https://github.com/agstack/inatrace-mobile.git
cd inatrace-mobile
npm install
# Configure .env (API URIs, MapBox tokens)
npx expo run:android # or run:ios⛓️ inatrace-coffee-network — Hyperledger Fabric Blockchain
The blockchain layer — a Hyperledger Fabric network with smart contracts (chaincode) that provide immutable, auditable records for supply chain transactions.
| Stack | Hyperledger Fabric, Docker, CouchDB, Go chaincode |
| Based On | BasicNetwork-2.0, Fabric Samples |
| License | MPL-2.0 |
| Last Updated | 2025-11-20 |
| Documentation | Hyperledger Fabric Docs |
Cross-repo technical specifications, integration designs, and enhancement proposals live in this meta repository. These documents describe work that spans multiple INATrace components or connects INATrace to external systems.
| Document | Status | Summary |
|---|---|---|
| Asset Registry Integration | 📋 Draft | Full spec for INATrace ↔ AgStack Asset Registry. Includes current state analysis, gap analysis, proposed architecture (async queue, ListIDs, EUDR pipeline), 5-phase roadmap, and task breakdown. |
| EUDR Compliance Pipeline | 🔜 Planned | Automated deforestation risk assessment via Whisp API, feeding compliance scores back into INATrace for batch reporting. |
| Asset Registry v2.0 Migration | 🔜 Planned | Hub+Node federation, WKT masking, ListIDs, shared identity — adapting INATrace for the next-gen registry. |
💡 Want to propose an enhancement? Open an issue in this repo with the
enhancementlabel, or submit a spec document as a PR.
⚠️ Partial Integration — Spec & Roadmap Available
INATrace has an existing but limited integration with the AgStack Asset Registry. When farmer plots are created with polygon coordinates, INATrace calls the Asset Registry's /register-field-boundary API to obtain a GeoID — a deterministic 64-character identifier for each geospatial boundary.
| Feature | Status | Details |
|---|---|---|
| Plot → GeoID registration | ✅ Implemented | AgStackClientService.java calls Asset Registry on plot create/update |
| GeoID stored in database | ✅ Implemented | Plot.geoId column persists the identifier |
| GeoID displayed in UI | ✅ Implemented | Web (Angular) + Mobile (React Native) show GeoID with copy button |
| "Open in Whisp" (EUDR analysis) | ✅ Implemented | Opens whisp.earthmap.org with GeoID |
| Manual GeoID refresh | ✅ Implemented | POST /userCustomers/{id}/plots/{plotId}/updateGeoID |
| GeoID in Excel export | ✅ Implemented | Included in farmer data exports |
| Gap | Severity |
|---|---|
| 🔴 Silent failure — registration errors return null with no user notification | Critical |
| 🔴 No batch registration — Excel farmer import skips GeoID generation | Critical |
| 🔴 Integration disabled by default — config values are empty in template | Critical |
| 🟡 No reverse lookup (GeoID → boundary from registry) | Medium |
| 🟡 No GeoID history/versioning when boundaries change | Medium |
| 🟡 No overlap intelligence surfaced to users | Medium |
| 🟡 No automated EUDR compliance pipeline (Whisp is view-only) | Medium |
| 🟡 No preparation for Asset Registry v2.0 (federated Hub+Node, ListIDs) | Medium |
👉 Full technical specification: ASSET_REGISTRY_INTEGRATION.md
| Metric | Backend | Frontend | Mobile | Blockchain | Total |
|---|---|---|---|---|---|
| ⭐ Stars | 8 | 1 | 0 | 1 | 10 |
| 🍴 Forks | 6 | 5 | 2 | 3 | 16 |
| 🐛 Open Issues | 4 | 0 | 0 | 0 | 4 |
| 📅 Created | 2020-11 | 2020-11 | 2024-12 | 2020-11 | — |
| 📝 Last Push | 2025-12-24 | 2025-12-24 | 2025-12-24 | 2025-11-20 | — |
 @pece-a 1,492 commits · Backend & Frontend lead |
 @RebernikNejc 301 commits · Backend & Frontend |
 @borce-paspalovski 223 commits · Frontend |
 @pinokokol 120 commits · Mobile lead |
 @MusicDin 148 commits · Backend |
 @MHA10 186 commits · Backend |
 @dockerymick 163 commits |
 @genovoxx 108 commits · Frontend |
 @sumerjohal AgStack core team |
 @MBJuric Mobile & Blockchain |
INATrace 2 is a major release that significantly expanded the platform:
- ✅ Generic value chain support — configure different commodity chains with specific settings
- ✅ Multi-tenant architecture — multiple organizations in one deployment
- ✅ Company profiles — facilities, processing actions, farmers, and collectors per company
- ✅ Product admin companies — delegated product management within value chains
- ✅ Processing actions — multiple types including bulk purchases for semi-products
- ✅ Final products — output of final processing, configurable by product admins
- ✅ Customer orders — linked to final products
- ✅ Purchases, processing & payments — comprehensive workflow management
- ✅ Farmer import — bulk import from Excel files
- ✅ Processing evidence fields — configurable in system settings
- ✅ Multi-language support — translations for facilities, actions, semi-products, and evidence types
- ✅ Multi-currency — configurable currencies with daily exchange rate sync via exchangeratesapi.io
- ✅ EUDR compliance — EU Deforestation Regulation support through polygon mapping and traceability
- ✅ GPS polygon mapping — field boundary capture on mobile devices
- ✅ Offline-first — full data collection without connectivity
- ✅ Auto-sync — seamless data synchronization when online
- ✅ Available on Google Play and App Store
To deploy the complete INATrace platform, you'll need to set up:
- Database — MySQL 8.4+ (can use Docker)
- Backend — Java 17 + Spring Boot API server
- Frontend — Angular web application
- Mobile (optional) — React Native app via Expo
- Blockchain (optional) — Hyperledger Fabric network
# 1. Clone all repositories
git clone https://github.com/agstack/inatrace-backend.git
git clone https://github.com/agstack/inatrace-frontend.git
git clone https://github.com/agstack/inatrace-mobile.git
git clone https://github.com/agstack/inatrace-coffee-network.git
# 2. Start MySQL
docker run --name inatrace-mysql \
-e MYSQL_ROOT_PASSWORD=root \
-e MYSQL_DATABASE=inatrace \
-e MYSQL_USER=inatrace \
-e MYSQL_PASSWORD=inatrace \
-p 3306:3306 -d mysql:8.4.6
# 3. Start Backend (see inatrace-backend README for full config)
cd inatrace-backend
# Configure application.properties
mvn spring-boot:run
# 4. Start Frontend
cd ../inatrace-frontend
npm install && ng serve
# 5. (Optional) Start Mobile
cd ../inatrace-mobile
npm install && npx expo run:androidFor detailed setup instructions, see each repository's README.
INATrace is part of the broader AgStack Foundation ecosystem of open digital infrastructure for agriculture:
| Project | Description |
|---|---|
| TraceFoodChain | Flutter app for tracing goods along food production chains |
| TerraTrac | EUDR compliance mobile app by TechnoServe Labs |
| Asset Registry | Geospatial asset registration for agricultural land |
| OpenAgri Platform | Modular digital agriculture microservices |
👉 See all AgStack projects: github.com/agstack
Governance documents are being established for the INATrace project.
This meta repository is the canonical location for:
- Project Charter — Mission, scope, and guiding principles
- Governance Model — Decision-making process, maintainer roles, voting procedures
- Code of Conduct — Community standards and enforcement
- Release Process — How releases are coordinated across the four component repos
These documents will be added as the governance framework is formalized. For now, INATrace operates under the broader AgStack Foundation governance.
| Document | Status |
|---|---|
CHARTER.md |
🔜 Planned |
GOVERNANCE.md |
🔜 Planned |
CODE_OF_CONDUCT.md |
🔜 Planned |
RELEASE_PROCESS.md |
🔜 Planned |
All INATrace repositories are licensed under the Mozilla Public License 2.0 (MPL-2.0).
We welcome contributions of all kinds — code, documentation, specs, and ideas!
| Type of contribution | Where |
|---|---|
| Bug fix or feature in backend, frontend, mobile, or blockchain | The relevant component repository |
| Cross-repo enhancement proposal or technical spec | This meta repo — open an issue or submit a spec PR |
| Governance, charter, or process proposal | This meta repo |
| Integration design (Asset Registry, EUDR, etc.) | This meta repo — see specs section |
| General question or discussion | This meta repo — open a discussion or issue |
- Browse open issues across INATrace repos
- Fork the relevant repository
- Create a feature branch and submit a pull request
- See individual repo READMEs for development setup details
Backend · Frontend · Mobile · Blockchain
Part of The AgStack Foundation · A Linux Foundation Project