Skip to main content

Architecture

Green Goods is a Bun monorepo with six runtime packages: contracts, shared, indexer, client, admin, and agent. Code and package guides own their boundaries; this page is the map for finding the right owner.

Dependency direction​

contracts → shared → client / admin / agent
    └─────→ indexer
  • packages/contracts owns protocol state, authorization, attestations, and deployment artifacts.
  • packages/shared owns cross-application hooks, modules, providers, types, and UI foundations.
  • packages/indexer projects contract events into queryable read models.
  • packages/client owns the public website and installed PWA.
  • packages/admin owns the steward cockpit.
  • packages/agent owns messaging and public HTTP surfaces.

Read the nearest package AGENTS.md before changing a package. Use the generated API index, entity diagram, and deployment status for volatile inventories.

Decisions that do not belong in code​

Architecture rationale, rejected alternatives, and cross-package sequencing belong in the owning Plan Hub or an ADR-style record. Public docs explain stable boundaries and user flows; they do not copy exports, routes, addresses, or implementation walkthroughs.