Architecture
Green Goods is an offline-first, single-chain platform for documenting regenerative work on-chain. The system is built as a Bun monorepo with six documented package surfaces that communicate through clearly defined boundaries.
Package boundaries
| Package | Responsibility |
|---|---|
packages/client | Gardener-facing PWA UI |
packages/admin | Operator-facing dashboard UI |
packages/shared | Hooks, providers, stores, business logic |
packages/contracts | Solidity modules + deployment scripts |
packages/indexer | Envio event indexing and GraphQL surface |
packages/agent | Automation/bot workflows |
Architecture principles
- DRY for shared hooks, query keys, and deployment addresses.
- KISS for chain/environment model -- single chain set by
VITE_CHAIN_ID. - YAGNI for config surface and feature toggles.
- Separation of concerns across packages with strict import boundaries.
- Offline-first -- the client PWA works without internet and syncs when connected.
- Graceful degradation -- optional contract modules fail silently via
try/catch.
System context
Green Goods is an offline-first, single-chain monorepo. Data flows in one direction: on-chain contracts emit events, the indexer (Envio) materializes those into GraphQL, and the frontends (Client PWA for gardeners, Admin Dashboard for operators) read everything through the @green-goods/shared hook layer — no frontend talks to a data source directly. The diagram below groups the packages into four colour-coded layers, top to bottom: frontends (green), the shared logic layer (blue), data sources (amber), and the on-chain contracts (pink). Read it as a dependency stack — each layer depends only on the one beneath it.
Deep dives
| Page | What you will learn |
|---|---|
| Local vs Global Balance | How the offline-first job queue and two-indexer read path keep the PWA responsive while data settles on-chain. |
| Entity Relationship Diagram | Every domain entity, its fields, and how they relate -- from on-chain events through the indexer to the frontend. |
| Modular Approach | The hub-and-spoke contract module system, package dependency graph, and Hats Protocol role tree. |
| Sequence Diagrams | Step-by-step flows for garden minting, work submission, vault deposits, passkey onboarding, and more. |
Next page
Next best action
Start with the offline-first architecture that makes Green Goods unique.
Local vs Global Balance