# trunganhlaptrinh/mini-agritrace architecture

> Architecture diagram of the GitHub repository trunganhlaptrinh/mini-agritrace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trunganhlaptrinh/mini-agritrace
- Repository: https://github.com/trunganhlaptrinh/mini-agritrace

## Overview

Mini AgriTrace is a consortium ledger application for signed agricultural batch histories. Organization users submit lifecycle and governance transactions; shipment proposals add a sender/carrier endorsement handoff. Services route submissions into the pending pool and block production, while nodes validate and synchronize ledger data. Public visitors can read allowlisted batch traces and open them via QR links. The graph also includes authentication, persistence, and offline consortium bootstrap. Most servlet, network, and projection details are represented at package level because their implementations were not sampled.

Main entry points: [`src/main/java/controller`](https://github.com/trunganhlaptrinh/mini-agritrace/tree/main/src/main/java/controller) (HTTP servlets), [`src/main/java/service/TransactionService.java`](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/TransactionService.java) (Transaction submission), [`src/main/java/blockchain/Blockchain.java`](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/Blockchain.java) (Chain replay and fork choice), [`src/main/java/service/PeerLedgerService.java`](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/PeerLedgerService.java) (Peer synchronization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web access"]
  node_servlets["HTTP servlets"]
  node_filters["Security filters"]
  node_browser_ui["Browser UI<br/>[app.js]"]
end

subgraph group_workflows["Application workflows"]
  node_auth["Authentication"]
  node_batch["Batch workflows<br/>[BatchService.java]"]
  node_shipment["Shipment handoff"]
  node_trace["Public trace"]
  node_governance["Governance workflows"]
  node_tx_service["Transaction submission"]
end

subgraph group_ledger["Ledger and governance"]
  node_tx_pool["Pending pool"]
  node_block_producer["Block production<br/>[BlockProducer.java]"]
  node_chain["Chain replay and fork choice<br/>[Blockchain.java]"]
  node_validation["Block validation"]
  node_validation_context["Validation context"]
  node_governance_registry["Canonical governance state"]
  node_block_repo["Block repository"]
end

subgraph group_consortium["Consortium operations"]
  node_peer_sync["Peer synchronization"]
  node_peer_network["Peer transport and relays"]
  node_bootstrap["Offline bootstrap"]
end

subgraph group_storage["Persistence"]
  node_transaction_dao["Transaction persistence"]
  node_block_dao["Block persistence<br/>[BlockDAO.java]"]
  node_user_dao["Account persistence<br/>[UserDAO.java]"]
  node_mysql[("MySQL node database")]
end

node_browser(("Users and visitors"))
node_peer(("Consortium peers"))

node_browser -->|"uses"| node_browser_ui
node_browser_ui -->|"calls"| node_servlets
node_servlets -->|"passes through"| node_filters
node_servlets -->|"invokes"| node_auth
node_servlets -.->|"invokes"| node_batch
node_servlets -.->|"invokes"| node_shipment
node_servlets -.->|"invokes"| node_trace
node_servlets -.->|"invokes"| node_governance
node_batch -->|"submits events"| node_tx_service
node_governance -->|"submits changes"| node_tx_service
node_shipment -->|"checks canonical state"| node_chain
node_shipment -.->|"submits endorsed event"| node_tx_service
node_trace -->|"reads chain state"| node_chain
node_auth -->|"reads accounts"| node_user_dao
node_tx_service -->|"submits transactions"| node_tx_pool
node_tx_service -->|"produces block"| node_block_producer
node_tx_service -->|"reads status"| node_transaction_dao
node_chain -->|"loads and stores blocks"| node_block_repo
node_chain -->|"validates blocks"| node_validation
node_validation -->|"uses context"| node_validation_context
node_peer -->|"exchanges ledger data"| node_peer_network
node_peer_network -->|"delivers peer data"| node_peer_sync
node_peer_sync -->|"processes blocks"| node_chain
node_peer_sync -->|"submits transactions"| node_tx_service
node_peer_sync -->|"accesses pending data"| node_transaction_dao
node_bootstrap -->|"validates ledger"| node_chain
node_bootstrap -->|"initializes blocks"| node_block_dao
node_bootstrap -->|"creates admin account"| node_user_dao
node_transaction_dao -->|"persists transactions"| node_mysql
node_block_dao -->|"persists blocks"| node_mysql
node_user_dao -->|"persists accounts"| node_mysql

click node_servlets "https://github.com/trunganhlaptrinh/mini-agritrace/tree/main/src/main/java/controller"
click node_filters "https://github.com/trunganhlaptrinh/mini-agritrace/tree/main/src/main/java/security"
click node_browser_ui "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/webapp/js/app.js"
click node_auth "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/AuthenticationService.java"
click node_batch "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/BatchService.java"
click node_shipment "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/ShipmentProposalService.java"
click node_trace "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/TraceabilityService.java"
click node_governance "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/GovernanceService.java"
click node_tx_service "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/TransactionService.java"
click node_tx_pool "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/TransactionPool.java"
click node_block_producer "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/BlockProducer.java"
click node_chain "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/Blockchain.java"
click node_validation "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/BlockValidator.java"
click node_validation_context "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/BlockValidationContext.java"
click node_governance_registry "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/GovernanceRegistry.java"
click node_block_repo "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/BlockRepository.java"
click node_peer_sync "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/PeerLedgerService.java"
click node_peer_network "https://github.com/trunganhlaptrinh/mini-agritrace/tree/main/src/main/java/network"
click node_bootstrap "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/bootstrap/ConsortiumBootstrapService.java"
click node_transaction_dao "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/dal/TransactionDAO.java"
click node_block_dao "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/dal/BlockDAO.java"
click node_user_dao "https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/dal/UserDAO.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_servlets,node_filters,node_browser_ui,node_browser toneBlue
class node_auth,node_batch,node_shipment,node_trace,node_governance,node_tx_service toneAmber
class node_tx_pool,node_block_producer,node_chain,node_validation,node_validation_context,node_governance_registry,node_block_repo toneMint
class node_peer_sync,node_peer_network,node_bootstrap toneRose
class node_transaction_dao,node_block_dao,node_user_dao,node_mysql,node_peer toneIndigo
```

## Components

### Web access

- [HTTP servlets](https://github.com/trunganhlaptrinh/mini-agritrace/tree/main/src/main/java/controller): `src/main/java/controller`
- [Security filters](https://github.com/trunganhlaptrinh/mini-agritrace/tree/main/src/main/java/security): `src/main/java/security`
- [Browser UI](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/webapp/js/app.js): `src/main/webapp/js/app.js`

### Application workflows

- [Authentication](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/AuthenticationService.java): `src/main/java/service/AuthenticationService.java`
- [Batch workflows](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/BatchService.java): `src/main/java/service/BatchService.java`
- [Shipment handoff](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/ShipmentProposalService.java): `src/main/java/service/ShipmentProposalService.java`
- [Public trace](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/TraceabilityService.java): `src/main/java/service/TraceabilityService.java`
- [Governance workflows](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/GovernanceService.java): `src/main/java/service/GovernanceService.java`
- [Transaction submission](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/TransactionService.java): `src/main/java/service/TransactionService.java`

### Ledger and governance

- [Pending pool](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/TransactionPool.java): `src/main/java/blockchain/TransactionPool.java`
- [Block production](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/BlockProducer.java): `src/main/java/blockchain/BlockProducer.java`
- [Chain replay and fork choice](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/Blockchain.java): `src/main/java/blockchain/Blockchain.java`
- [Block validation](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/BlockValidator.java): `src/main/java/blockchain/BlockValidator.java`
- [Validation context](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/BlockValidationContext.java): `src/main/java/blockchain/BlockValidationContext.java`
- [Canonical governance state](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/GovernanceRegistry.java): `src/main/java/blockchain/GovernanceRegistry.java`
- [Block repository](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/blockchain/BlockRepository.java): `src/main/java/blockchain/BlockRepository.java`

### Consortium operations

- [Peer synchronization](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/service/PeerLedgerService.java): `src/main/java/service/PeerLedgerService.java`
- [Peer transport and relays](https://github.com/trunganhlaptrinh/mini-agritrace/tree/main/src/main/java/network): `src/main/java/network`
- [Offline bootstrap](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/bootstrap/ConsortiumBootstrapService.java): `src/main/java/bootstrap/ConsortiumBootstrapService.java`

### Persistence

- [Transaction persistence](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/dal/TransactionDAO.java): `src/main/java/dal/TransactionDAO.java`
- [Block persistence](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/dal/BlockDAO.java): `src/main/java/dal/BlockDAO.java`
- [Account persistence](https://github.com/trunganhlaptrinh/mini-agritrace/blob/main/src/main/java/dal/UserDAO.java): `src/main/java/dal/UserDAO.java`
- **MySQL node database**

### Other components

- **Users and visitors**
- **Consortium peers**

## Connections

- Users and visitors → Browser UI: uses
- Browser UI → HTTP servlets: calls
- HTTP servlets → Security filters: passes through (evidence: `src/main/java/controller/AuthenticationSessionServlet.java`)
- HTTP servlets → Authentication: invokes (evidence: `src/main/java/controller/AuthenticationSessionServlet.java`)
- HTTP servlets → Batch workflows: invokes
- HTTP servlets → Shipment handoff: invokes
- HTTP servlets → Public trace: invokes
- HTTP servlets → Governance workflows: invokes
- Batch workflows → Transaction submission: submits events (evidence: `src/main/java/service/BatchService.java`)
- Governance workflows → Transaction submission: submits changes (evidence: `src/main/java/service/GovernanceService.java`)
- Shipment handoff → Chain replay and fork choice: checks canonical state (evidence: `src/main/java/service/ShipmentProposalService.java`)
- Shipment handoff → Transaction submission: submits endorsed event (evidence: `src/main/java/service/ShipmentProposalService.java`)
- Public trace → Chain replay and fork choice: reads chain state (evidence: `src/main/java/service/TraceabilityService.java`)
- Authentication → Account persistence: reads accounts (evidence: `src/main/java/service/AuthenticationService.java`)
- Transaction submission → Pending pool: submits transactions (evidence: `src/main/java/service/TransactionService.java`)
- Transaction submission → Block production: produces block (evidence: `src/main/java/service/TransactionService.java`)
- Transaction submission → Transaction persistence: reads status (evidence: `src/main/java/service/TransactionService.java`)
- Chain replay and fork choice → Block repository: loads and stores blocks (evidence: `src/main/java/blockchain/Blockchain.java`)
- Chain replay and fork choice → Block validation: validates blocks (evidence: `src/main/java/blockchain/Blockchain.java`)
- Block validation → Validation context: uses context (evidence: `src/main/java/blockchain/BlockValidationContext.java`)
- Consortium peers → Peer transport and relays: exchanges ledger data
- Peer transport and relays → Peer synchronization: delivers peer data (evidence: `src/main/java/network/PeerClient.java`)
- Peer synchronization → Chain replay and fork choice: processes blocks (evidence: `src/main/java/service/PeerLedgerService.java`)
- Peer synchronization → Transaction submission: submits transactions (evidence: `src/main/java/service/PeerLedgerService.java`)
- Peer synchronization → Transaction persistence: accesses pending data (evidence: `src/main/java/service/PeerLedgerService.java`)
- Offline bootstrap → Chain replay and fork choice: validates ledger (evidence: `src/main/java/bootstrap/ConsortiumBootstrapService.java`)
- Offline bootstrap → Block persistence: initializes blocks (evidence: `src/main/java/bootstrap/ConsortiumBootstrapService.java`)
- Offline bootstrap → Account persistence: creates admin account (evidence: `src/main/java/bootstrap/ConsortiumBootstrapService.java`)
- Transaction persistence → MySQL node database: persists transactions
- Block persistence → MySQL node database: persists blocks
- Account persistence → MySQL node database: persists accounts
