# krishnakeshab-banik/honeychain architecture

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

- Interactive diagram: https://gitdiagram.com/krishnakeshab-banik/honeychain
- Repository: https://github.com/krishnakeshab-banik/honeychain

## Overview

HoneyChain is a role-scoped KVIC honey traceability and intelligence platform. Its central workflow records hive signals and beekeeper harvests, groups harvests into batches, requires lab approval and a weight-oracle check, seals passing batches in a local hash-chain, issues package QR identities, and lets the public verify them without an account. Separate capabilities support CloneWatch, colony insights, market linkage, analytics, and an optional grounded assistant. The README documents these stages; unsampled router and service internals limit certainty about some call wiring.

Main entry points: [`backend/routers`](https://github.com/krishnakeshab-banik/honeychain/tree/main/backend/routers) (Domain routers), [`backend/database.py`](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/database.py) (SQLite database), [`web/src/App.jsx`](https://github.com/krishnakeshab-banik/honeychain/blob/main/web/src/App.jsx) (React application), [`backend/main.py`](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interfaces"]
  node_web_ui["React application<br/>[App.jsx]"]
  node_web_api["Browser API client<br/>[api.js]"]
  node_streamlit_ui["Streamlit dashboard<br/>[app.py]"]
end

subgraph group_api["API routing"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_routers["Domain routers"]
  node_auth["Authentication<br/>[auth_service.py]"]
end

subgraph group_trace["Traceability workflow"]
  node_sensor["Hive telemetry<br/>[sensor_service.py]"]
  node_harvest["Harvest records<br/>[harvest_service.py]"]
  node_batch["Batch workflow<br/>[batch_service.py]"]
  node_lab["Lab inspection<br/>[lab_service.py]"]
  node_oracle["Weight oracle<br/>[oracle_service.py]"]
  node_ledger["Hash-chain ledger<br/>[ledger_service.py]"]
  node_package["Package and QR<br/>[package_service.py]"]
  node_public_verify["Public verification<br/>[public_service.py]"]
end

subgraph group_intelligence["Intelligence and linkage"]
  node_clonewatch["CloneWatch"]
  node_insights["Colony insights<br/>[ml_service.py]"]
  node_market["Market linkage<br/>[market_service.py]"]
  node_analytics["Cluster analytics"]
  node_assistant["Grounded assistant"]
end

subgraph group_state["Persistence"]
  node_database[("SQLite database<br/>[database.py]")]
end

node_beekeeper(("Beekeeper"))
node_officer(("KVIC officer"))
node_lab_user(("Lab inspector"))
node_buyer(("Citizen or buyer"))
node_hive_sim["Hive simulator<br/>[hive_simulator.py]"]
node_gemini["Gemini API"]

node_beekeeper -->|"uses"| node_web_ui
node_officer -->|"uses"| node_web_ui
node_lab_user -->|"uses"| node_web_ui
node_buyer -->|"verifies via"| node_web_ui
node_hive_sim -.->|"sends readings"| node_api_app
node_web_ui -->|"requests"| node_web_api
node_web_api -->|"calls API"| node_api_app
node_streamlit_ui -->|"calls API"| node_api_app
node_api_app -->|"mounts routes"| node_routers
node_routers -->|"delegates auth"| node_auth
node_routers -->|"delegates telemetry"| node_sensor
node_routers -->|"delegates harvests"| node_harvest
node_routers -->|"delegates batches"| node_batch
node_routers -->|"delegates tests"| node_lab
node_routers -->|"runs checks"| node_oracle
node_routers -->|"seals records"| node_ledger
node_routers -->|"issues packages"| node_package
node_routers -->|"serves verification"| node_public_verify
node_routers -->|"serves scan monitoring"| node_clonewatch
node_routers -->|"requests predictions"| node_insights
node_routers -->|"serves listings"| node_market
node_routers -->|"serves analytics"| node_analytics
node_routers -->|"dispatches questions"| node_assistant
node_assistant -.->|"requests language"| node_gemini
node_web_ui -->|"presents passport"| node_public_verify
node_web_ui -->|"presents alerts"| node_clonewatch
node_web_ui -->|"presents insights"| node_insights
node_web_ui -->|"presents market"| node_market
node_sensor -->|"stores readings"| node_database
node_harvest -->|"stores harvests"| node_database
node_batch -->|"stores batches"| node_database
node_lab -->|"stores results"| node_database
node_oracle -->|"reads scale data"| node_database
node_ledger -->|"stores chain"| node_database
node_package -->|"stores package IDs"| node_database
node_public_verify -->|"checks ledger rows"| node_database
node_clonewatch -->|"reads scan records"| node_database
node_insights -->|"reads sensor history"| node_database
node_market -->|"stores listings"| node_database
node_analytics -->|"reads cluster data"| node_database
node_auth -->|"reads and writes users"| node_database

click node_hive_sim "https://github.com/krishnakeshab-banik/honeychain/blob/main/simulator/hive_simulator.py"
click node_web_ui "https://github.com/krishnakeshab-banik/honeychain/blob/main/web/src/App.jsx"
click node_web_api "https://github.com/krishnakeshab-banik/honeychain/blob/main/web/src/api.js"
click node_streamlit_ui "https://github.com/krishnakeshab-banik/honeychain/blob/main/frontend/app.py"
click node_api_app "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/main.py"
click node_routers "https://github.com/krishnakeshab-banik/honeychain/tree/main/backend/routers"
click node_auth "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/auth_service.py"
click node_sensor "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/sensor_service.py"
click node_harvest "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/harvest_service.py"
click node_batch "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/batch_service.py"
click node_lab "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/lab_service.py"
click node_oracle "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/oracle_service.py"
click node_ledger "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/ledger_service.py"
click node_package "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/package_service.py"
click node_public_verify "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/public_service.py"
click node_clonewatch "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/clonewatch_service.py"
click node_insights "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/ml_service.py"
click node_market "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/market_service.py"
click node_analytics "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/analytics_service.py"
click node_assistant "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/assistant_service.py"
click node_database "https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/database.py"

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_web_ui,node_web_api,node_streamlit_ui toneBlue
class node_api_app,node_routers,node_auth toneAmber
class node_sensor,node_harvest,node_batch,node_lab,node_oracle,node_ledger,node_package,node_public_verify,node_gemini toneMint
class node_clonewatch,node_insights,node_market,node_analytics,node_assistant toneRose
class node_database,node_beekeeper,node_officer,node_lab_user,node_buyer toneIndigo
class node_hive_sim toneTeal
```

## Components

### User interfaces

- [React application](https://github.com/krishnakeshab-banik/honeychain/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Browser API client](https://github.com/krishnakeshab-banik/honeychain/blob/main/web/src/api.js): `web/src/api.js`
- [Streamlit dashboard](https://github.com/krishnakeshab-banik/honeychain/blob/main/frontend/app.py): `frontend/app.py`

### API routing

- [FastAPI application](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/main.py): `backend/main.py`
- [Domain routers](https://github.com/krishnakeshab-banik/honeychain/tree/main/backend/routers): `backend/routers`
- [Authentication](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`

### Traceability workflow

- [Hive telemetry](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/sensor_service.py): `backend/services/sensor_service.py`
- [Harvest records](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/harvest_service.py): `backend/services/harvest_service.py`
- [Batch workflow](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/batch_service.py): `backend/services/batch_service.py`
- [Lab inspection](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/lab_service.py): `backend/services/lab_service.py`
- [Weight oracle](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/oracle_service.py): `backend/services/oracle_service.py`
- [Hash-chain ledger](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/ledger_service.py): `backend/services/ledger_service.py`
- [Package and QR](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/package_service.py): `backend/services/package_service.py`
- [Public verification](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/public_service.py): `backend/services/public_service.py`

### Intelligence and linkage

- [CloneWatch](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/clonewatch_service.py): `backend/services/clonewatch_service.py`
- [Colony insights](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/ml_service.py): `backend/services/ml_service.py`
- [Market linkage](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/market_service.py): `backend/services/market_service.py`
- [Cluster analytics](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/analytics_service.py): `backend/services/analytics_service.py`
- [Grounded assistant](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/services/assistant_service.py): `backend/services/assistant_service.py`

### Persistence

- [SQLite database](https://github.com/krishnakeshab-banik/honeychain/blob/main/backend/database.py): `backend/database.py`

### Other components

- **Beekeeper**
- **KVIC officer**
- **Lab inspector**
- **Citizen or buyer**
- [Hive simulator](https://github.com/krishnakeshab-banik/honeychain/blob/main/simulator/hive_simulator.py): `simulator/hive_simulator.py`
- **Gemini API**

## Connections

- Beekeeper → React application: uses
- KVIC officer → React application: uses
- Lab inspector → React application: uses
- Citizen or buyer → React application: verifies via
- Hive simulator → FastAPI application: sends readings
- React application → Browser API client: requests
- Browser API client → FastAPI application: calls API
- Streamlit dashboard → FastAPI application: calls API
- FastAPI application → Domain routers: mounts routes
- Domain routers → Authentication: delegates auth
- Domain routers → Hive telemetry: delegates telemetry
- Domain routers → Harvest records: delegates harvests
- Domain routers → Batch workflow: delegates batches
- Domain routers → Lab inspection: delegates tests
- Domain routers → Weight oracle: runs checks
- Domain routers → Hash-chain ledger: seals records
- Domain routers → Package and QR: issues packages
- Domain routers → Public verification: serves verification
- Domain routers → CloneWatch: serves scan monitoring
- Domain routers → Colony insights: requests predictions
- Domain routers → Market linkage: serves listings
- Domain routers → Cluster analytics: serves analytics
- Domain routers → Grounded assistant: dispatches questions
- Grounded assistant → Gemini API: requests language
- React application → Public verification: presents passport
- React application → CloneWatch: presents alerts
- React application → Colony insights: presents insights
- React application → Market linkage: presents market
- Hive telemetry → SQLite database: stores readings
- Harvest records → SQLite database: stores harvests
- Batch workflow → SQLite database: stores batches
- Lab inspection → SQLite database: stores results
- Weight oracle → SQLite database: reads scale data
- Hash-chain ledger → SQLite database: stores chain
- Package and QR → SQLite database: stores package IDs
- Public verification → SQLite database: checks ledger rows
- CloneWatch → SQLite database: reads scan records
- Colony insights → SQLite database: reads sensor history
- Market linkage → SQLite database: stores listings
- Cluster analytics → SQLite database: reads cluster data
- Authentication → SQLite database: reads and writes users