# manushwi/madhuchain architecture

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

- Interactive diagram: https://gitdiagram.com/manushwi/madhuchain
- Repository: https://github.com/manushwi/madhuchain

## Overview

MadhuChain is a honey traceability system: beekeeper and factory workflows record supply-chain events, while consumers scan jar codes to inspect provenance and authenticity. The backend coordinates app-facing workflows, database records, analytics and fraud checks, and a permissioned Fabric ledger; a KVIC dashboard supports review and administration. The README documents the end-to-end capabilities, but several app screens and backend subsystems were not sampled, so those links are documented rather than inferred from unsampled code.

Main entry points: [`services/backend/src/app.ts`](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/app.ts) (API router), [`services/backend/src/services/fabric/fabricService.ts`](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/services/fabric/fabricService.ts) (Fabric gateway), [`services/backend/src/db/prisma.ts`](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/db/prisma.ts) (Operational database), [`services/backend/src/routes/factory.ts`](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/factory.ts) (Factory workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_field["Field operations"]
  node_beekeeper["Beekeeper app<br/>[index.tsx]"]
  node_hive["Hive monitoring<br/>[hives.ts]"]
  node_sensor["Sensor ingestion<br/>[sensorData.ts]"]
  node_harvest["Harvest batches<br/>[batches.ts]"]
end

subgraph group_production["Factory operations"]
  node_factoryapp["Factory app<br/>[&#91;id&#93;.tsx]"]
  node_factory["Factory workflows<br/>[factory.ts]"]
  node_blend["Batch blending<br/>[create.tsx]"]
end

subgraph group_platform["Backend and ledger"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_api["API router<br/>[app.ts]"]
  node_database[("Operational database<br/>[prisma.ts]")]
  node_analytics["Hive analytics<br/>[hiveAnalytics.ts]"]
  node_risk["Fraud checks<br/>[fraudChecks.ts]"]
  node_fabric["Fabric gateway<br/>[fabricService.ts]"]
  node_chaincode["Ledger contract<br/>[contract.go]"]
  node_indexer["Ledger event indexer"]
end

subgraph group_trust["Verification and oversight"]
  node_consumer["Jar verification site<br/>[page.tsx]"]
  node_verify["Verification API<br/>[verify.ts]"]
  node_admin["KVIC dashboard<br/>[page.tsx]"]
  node_adminroutes["Administration routes<br/>[admin.ts]"]
end

node_beekeeperactor(("Beekeeper"))
node_factoryactor(("Factory worker"))
node_consumeractor(("Jar buyer"))
node_kvicactor(("KVIC reviewer"))

node_beekeeperactor -->|"uses"| node_beekeeper
node_beekeeper -.->|"requests"| node_api
node_api -->|"routes auth"| node_auth
node_api -->|"routes hive"| node_hive
node_api -->|"routes telemetry"| node_sensor
node_api -->|"routes batches"| node_harvest
node_hive -->|"reads and writes"| node_database
node_sensor -->|"stores readings"| node_database
node_sensor -->|"evaluates telemetry"| node_analytics
node_factoryactor -->|"uses"| node_factoryapp
node_factoryapp -.->|"requests"| node_api
node_api -->|"routes workflows"| node_factory
node_api -->|"supports blending"| node_blend
node_factory -->|"reads and writes"| node_database
node_factory -->|"checks batches"| node_risk
node_harvest -->|"records batches"| node_database
node_harvest -->|"stamps harvest"| node_fabric
node_factory -->|"records events"| node_fabric
node_fabric -->|"submits transactions"| node_chaincode
node_indexer -.->|"indexes events"| node_fabric
node_consumeractor -->|"scans jar code"| node_consumer
node_consumer -->|"fetches verification"| node_verify
node_verify -.->|"reads records"| node_database
node_verify -.->|"checks ledger proof"| node_fabric
node_kvicactor -->|"reviews batches"| node_admin
node_admin -.->|"requests oversight"| node_adminroutes
node_api -->|"routes admin"| node_adminroutes
node_adminroutes -->|"reads and writes"| node_database
node_adminroutes -->|"audits ledger"| node_fabric

click node_beekeeper "https://github.com/manushwi/madhuchain/blob/main/apps/beekeeper-app/app/(tabs)/index.tsx"
click node_hive "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/hives.ts"
click node_sensor "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/sensorData.ts"
click node_harvest "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/batches.ts"
click node_factoryapp "https://github.com/manushwi/madhuchain/blob/main/apps/factory-app/app/(tabs)/batch/%5Bid%5D.tsx"
click node_factory "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/factory.ts"
click node_blend "https://github.com/manushwi/madhuchain/blob/main/apps/factory-app/app/blend/create.tsx"
click node_auth "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/auth.ts"
click node_api "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/app.ts"
click node_database "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/db/prisma.ts"
click node_analytics "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/services/hiveAnalytics.ts"
click node_risk "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/services/fraudChecks.ts"
click node_fabric "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/services/fabric/fabricService.ts"
click node_chaincode "https://github.com/manushwi/madhuchain/blob/main/chain/chaincode/madhuchain-cc/contract.go"
click node_indexer "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/workers/fabricEventIndexer.ts"
click node_consumer "https://github.com/manushwi/madhuchain/blob/main/apps/consumer-web/app/v/%5Btoken%5D/page.tsx"
click node_verify "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/verify.ts"
click node_admin "https://github.com/manushwi/madhuchain/blob/main/apps/kvic-dashboard/app/(dashboard)/page.tsx"
click node_adminroutes "https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/admin.ts"

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_beekeeper,node_hive,node_sensor,node_harvest,node_kvicactor toneBlue
class node_factoryapp,node_factory,node_blend toneAmber
class node_auth,node_api,node_database,node_analytics,node_risk,node_fabric,node_chaincode,node_indexer toneMint
class node_consumer,node_verify,node_admin,node_adminroutes,node_factoryactor toneRose
class node_beekeeperactor,node_consumeractor toneIndigo
```

## Components

### Field operations

- [Beekeeper app](https://github.com/manushwi/madhuchain/blob/main/apps/beekeeper-app/app/(tabs)/index.tsx): `apps/beekeeper-app/app/(tabs)/index.tsx`
- [Hive monitoring](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/hives.ts): `services/backend/src/routes/hives.ts`
- [Sensor ingestion](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/sensorData.ts): `services/backend/src/routes/sensorData.ts`
- [Harvest batches](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/batches.ts): `services/backend/src/routes/batches.ts`

### Factory operations

- [Factory app](https://github.com/manushwi/madhuchain/blob/main/apps/factory-app/app/(tabs)/batch/%5Bid%5D.tsx): `apps/factory-app/app/(tabs)/batch/[id].tsx`
- [Factory workflows](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/factory.ts): `services/backend/src/routes/factory.ts`
- [Batch blending](https://github.com/manushwi/madhuchain/blob/main/apps/factory-app/app/blend/create.tsx): `apps/factory-app/app/blend/create.tsx`

### Backend and ledger

- [Authentication](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/auth.ts): `services/backend/src/routes/auth.ts`
- [API router](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/app.ts): `services/backend/src/app.ts`
- [Operational database](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/db/prisma.ts): `services/backend/src/db/prisma.ts`
- [Hive analytics](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/services/hiveAnalytics.ts): `services/backend/src/services/hiveAnalytics.ts`
- [Fraud checks](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/services/fraudChecks.ts): `services/backend/src/services/fraudChecks.ts`
- [Fabric gateway](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/services/fabric/fabricService.ts): `services/backend/src/services/fabric/fabricService.ts`
- [Ledger contract](https://github.com/manushwi/madhuchain/blob/main/chain/chaincode/madhuchain-cc/contract.go): `chain/chaincode/madhuchain-cc/contract.go`
- [Ledger event indexer](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/workers/fabricEventIndexer.ts): `services/backend/src/workers/fabricEventIndexer.ts`

### Verification and oversight

- [Jar verification site](https://github.com/manushwi/madhuchain/blob/main/apps/consumer-web/app/v/%5Btoken%5D/page.tsx): `apps/consumer-web/app/v/[token]/page.tsx`
- [Verification API](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/verify.ts): `services/backend/src/routes/verify.ts`
- [KVIC dashboard](https://github.com/manushwi/madhuchain/blob/main/apps/kvic-dashboard/app/(dashboard)/page.tsx): `apps/kvic-dashboard/app/(dashboard)/page.tsx`
- [Administration routes](https://github.com/manushwi/madhuchain/blob/main/services/backend/src/routes/admin.ts): `services/backend/src/routes/admin.ts`

### Other components

- **Beekeeper**
- **Factory worker**
- **Jar buyer**
- **KVIC reviewer**

## Connections

- Beekeeper → Beekeeper app: uses
- Beekeeper app → API router: requests
- API router → Authentication: routes auth (evidence: `services/backend/src/app.ts`)
- API router → Hive monitoring: routes hive (evidence: `services/backend/src/app.ts`)
- API router → Sensor ingestion: routes telemetry (evidence: `services/backend/src/app.ts`)
- API router → Harvest batches: routes batches (evidence: `services/backend/src/app.ts`)
- Hive monitoring → Operational database: reads and writes (evidence: `services/backend/src/routes/hives.ts`)
- Sensor ingestion → Operational database: stores readings (evidence: `services/backend/src/routes/sensorData.ts`)
- Sensor ingestion → Hive analytics: evaluates telemetry (evidence: `services/backend/src/routes/sensorData.ts`)
- Factory worker → Factory app: uses
- Factory app → API router: requests
- API router → Factory workflows: routes workflows (evidence: `services/backend/src/app.ts`)
- API router → Batch blending: supports blending (evidence: `services/backend/src/app.ts`)
- Factory workflows → Operational database: reads and writes (evidence: `services/backend/src/routes/factory.ts`)
- Factory workflows → Fraud checks: checks batches (evidence: `services/backend/src/routes/factory.ts`)
- Harvest batches → Operational database: records batches (evidence: `services/backend/src/routes/batches.ts`)
- Harvest batches → Fabric gateway: stamps harvest (evidence: `services/backend/src/routes/batches.ts`)
- Factory workflows → Fabric gateway: records events (evidence: `services/backend/src/routes/factory.ts`)
- Fabric gateway → Ledger contract: submits transactions
- Ledger event indexer → Fabric gateway: indexes events
- Jar buyer → Jar verification site: scans jar code
- Jar verification site → Verification API: fetches verification (evidence: `apps/consumer-web/app/v/[token]/page.tsx`)
- Verification API → Operational database: reads records
- Verification API → Fabric gateway: checks ledger proof
- KVIC reviewer → KVIC dashboard: reviews batches
- KVIC dashboard → Administration routes: requests oversight
- API router → Administration routes: routes admin (evidence: `services/backend/src/app.ts`)
- Administration routes → Operational database: reads and writes (evidence: `services/backend/src/routes/admin.ts`)
- Administration routes → Fabric gateway: audits ledger (evidence: `services/backend/src/routes/admin.ts`)
