GitHub - agstack/inatrace: INATrace — Open-source blockchain-based track and trace for agricultural supply chains. Meta repo linking backend, frontend, mobile, and blockchain components.

📌 About This Repository

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

Repository Structure

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.

🌍 What is INATrace?

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.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         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)    │
└─────────────────────────────────────────────────────────────────────┘

📦 Component Repositories

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

📐 Specifications & Enhancement 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 enhancement label, or submit a spec document as a PR.

🔗 AgStack Asset Registry Integration

⚠️ 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.

Current State

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

Known Gaps

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

📊 Project Stats

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	—

👥 Core Maintainers

_@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}

✨ Key Features (INATrace 2.x)

INATrace 2 is a major release that significantly expanded the platform:

Value Chain Management

✅ 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

Supply Chain Operations

✅ 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

Data & Compliance

✅ 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

Mobile & Field

✅ 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

🚀 Getting Started

Full Platform Deployment

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:android

For detailed setup instructions, see each repository's README.

🔗 Related Projects

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 & Charter

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

📜 License

All INATrace repositories are licensed under the Mozilla Public License 2.0 (MPL-2.0).

🤝 Contributing

We welcome contributions of all kinds — code, documentation, specs, and ideas!

Where to contribute

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

How to contribute

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