# fayizzbanday/beehive.fsoc architecture

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

- Interactive diagram: https://gitdiagram.com/fayizzbanday/beehive.fsoc
- Repository: https://github.com/fayizzbanday/beehive.fsoc

## Overview

Beehive.fsoc is a beekeeping digital-twin and honey-traceability application. Beekeepers register apiaries and hives, submit hive video scans for risk assessment, and record harvest batches; shoppers verify a jar’s public passport, while authorities review risk and tamper alerts. The graph separates the web experience, Worker domain services, analysis engines, and proof infrastructure. The README documents the end-to-end product flow, but the Worker router and several domain modules were not excerpted, so those links are shown as unverified rather than asserted calls.

Main entry points: [`beehive-main/apps/web/src/App.tsx`](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/App.tsx) (Web routes), [`beehive-main/apps/web/src/lib/api.ts`](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/lib/api.ts) (API client), [`beehive-main/apps/worker/src/index.ts`](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/index.ts) (API router), [`beehive-main/apps/worker/src/scans.ts`](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/scans.ts) (Scan handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_app["Web routes<br/>[App.tsx]"]
  node_scan_ui["Video scan<br/>[Scan.tsx]"]
  node_hive_ui["Hive management<br/>[Hives.tsx]"]
  node_batch_ui["Batch creation<br/>[BatchWizard.tsx]"]
  node_verify_ui["Public verification<br/>[Verify.tsx]"]
  node_authority_ui["Authority console<br/>[Authority.tsx]"]
  node_tamper_ui["Tamper review<br/>[Tamper.tsx]"]
  node_forecast_ui["Forecasting<br/>[Forecast.tsx]"]
  node_dashboard_ui["Hive dashboard<br/>[Dashboard.tsx]"]
  node_batch_list_ui["Batch records<br/>[Batches.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_worker["Worker services"]
  node_worker_router["API router<br/>[index.ts]"]
  node_auth["Sessions and roles<br/>[auth.ts]"]
  node_hives["Hive records<br/>[hives.ts]"]
  node_scans["Scan handling<br/>[scans.ts]"]
  node_batches["Batch records<br/>[batches.ts]"]
  node_documents["Evidence documents<br/>[documents.ts]"]
  node_authority["Oversight services<br/>[authority.ts]"]
  node_verification["Proof verification<br/>[verify.ts]"]
end

subgraph group_engines["Analysis engines"]
  node_scan_engine["Scan analysis<br/>[index.ts]"]
  node_forecast_engine["Forecast engine<br/>[forecast.ts]"]
  node_risk_engine["Risk assessment<br/>[index.ts]"]
end

subgraph group_integrity["Proof and records"]
  node_shared_types["Domain schemas<br/>[index.ts]"]
  node_proofs["Record proofs<br/>[proofs.ts]"]
  node_canonical["Canonical hashing<br/>[canonical.ts]"]
  node_chain_client["Blockchain client<br/>[index.ts]"]
  node_chain_registry["Registry interface<br/>[abi.ts]"]
end

node_beekeeper(("Beekeeper"))
node_shopper(("Shopper"))
node_authority_user(("Authority user"))
node_ethereum{{"Ethereum network"}}
node_database[("Worker database")]

node_web_app -->|"routes to"| node_scan_ui
node_web_app -->|"routes to"| node_hive_ui
node_web_app -->|"routes to"| node_batch_ui
node_web_app -->|"routes to"| node_verify_ui
node_web_app -->|"routes to"| node_authority_ui
node_web_app -->|"routes to"| node_tamper_ui
node_web_app -->|"routes to"| node_forecast_ui
node_web_app -->|"routes to"| node_dashboard_ui
node_web_app -->|"routes to"| node_batch_list_ui
node_beekeeper -.->|"submits video"| node_scan_ui
node_beekeeper -.->|"manages colonies"| node_hive_ui
node_beekeeper -.->|"records harvest"| node_batch_ui
node_shopper -.->|"scans jar"| node_verify_ui
node_authority_user -.->|"reviews alerts"| node_authority_ui
node_scan_ui -.->|"requests scans"| node_api_client
node_hive_ui -.->|"requests records"| node_api_client
node_batch_ui -.->|"submits batch"| node_api_client
node_verify_ui -.->|"requests proof"| node_api_client
node_authority_ui -->|"requests oversight"| node_api_client
node_tamper_ui -.->|"requests alerts"| node_api_client
node_forecast_ui -.->|"requests forecast"| node_api_client
node_dashboard_ui -->|"requests summaries"| node_api_client
node_batch_list_ui -->|"requests batches"| node_api_client
node_api_client -.->|"calls API"| node_worker_router
node_worker_router -.->|"dispatches auth"| node_auth
node_worker_router -.->|"dispatches hive routes"| node_hives
node_worker_router -.->|"dispatches scan routes"| node_scans
node_worker_router -.->|"dispatches batch routes"| node_batches
node_worker_router -.->|"dispatches documents"| node_documents
node_worker_router -.->|"dispatches oversight"| node_authority
node_worker_router -.->|"dispatches verification"| node_verification
node_scans -.->|"analyzes frames"| node_scan_engine
node_scan_engine -->|"uses classification"| node_risk_engine
node_forecast_ui -.->|"renders forecast"| node_forecast_engine
node_batches -.->|"assesses metadata"| node_risk_engine
node_scans -.->|"stores scan"| node_database
node_hives -.->|"stores hive"| node_database
node_batches -.->|"stores batch"| node_database
node_authority -.->|"reads alerts"| node_database
node_verification -.->|"checks proof"| node_proofs
node_proofs -.->|"hashes record"| node_canonical
node_proofs -.->|"anchors record"| node_chain_client
node_verification -.->|"reads anchor"| node_chain_client
node_chain_client -->|"uses ABI"| node_chain_registry
node_chain_client -.->|"reads and writes"| node_ethereum
node_scans -.->|"uses schemas"| node_shared_types
node_batches -.->|"uses schemas"| node_shared_types
node_risk_engine -->|"uses domain types"| node_shared_types

click node_web_app "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/App.tsx"
click node_scan_ui "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Scan.tsx"
click node_hive_ui "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Hives.tsx"
click node_batch_ui "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/BatchWizard.tsx"
click node_verify_ui "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Verify.tsx"
click node_authority_ui "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Authority.tsx"
click node_tamper_ui "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Tamper.tsx"
click node_forecast_ui "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Forecast.tsx"
click node_dashboard_ui "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Dashboard.tsx"
click node_batch_list_ui "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Batches.tsx"
click node_api_client "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/lib/api.ts"
click node_worker_router "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/index.ts"
click node_auth "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/auth.ts"
click node_hives "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/hives.ts"
click node_scans "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/scans.ts"
click node_batches "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/batches.ts"
click node_documents "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/documents.ts"
click node_authority "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/authority.ts"
click node_verification "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/verify.ts"
click node_shared_types "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/shared/src/index.ts"
click node_scan_engine "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/scan-engine/src/index.ts"
click node_forecast_engine "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/scan-engine/src/forecast.ts"
click node_risk_engine "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/risk-engine/src/index.ts"
click node_proofs "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/proofs.ts"
click node_canonical "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/shared/src/canonical.ts"
click node_chain_client "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/blockchain/src/index.ts"
click node_chain_registry "https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/blockchain/src/abi.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_web_app,node_scan_ui,node_hive_ui,node_batch_ui,node_verify_ui,node_authority_ui,node_tamper_ui,node_forecast_ui,node_dashboard_ui,node_batch_list_ui,node_api_client,node_authority_user toneBlue
class node_worker_router,node_auth,node_hives,node_scans,node_batches,node_documents,node_authority,node_verification,node_database toneAmber
class node_scan_engine,node_forecast_engine,node_risk_engine toneMint
class node_shared_types,node_proofs,node_canonical,node_chain_client,node_chain_registry toneRose
class node_beekeeper,node_shopper,node_ethereum toneIndigo
```

## Components

### Web experience

- [Web routes](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/App.tsx): `beehive-main/apps/web/src/App.tsx`
- [Video scan](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Scan.tsx): `beehive-main/apps/web/src/pages/Scan.tsx`
- [Hive management](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Hives.tsx): `beehive-main/apps/web/src/pages/Hives.tsx`
- [Batch creation](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/BatchWizard.tsx): `beehive-main/apps/web/src/pages/BatchWizard.tsx`
- [Public verification](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Verify.tsx): `beehive-main/apps/web/src/pages/Verify.tsx`
- [Authority console](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Authority.tsx): `beehive-main/apps/web/src/pages/Authority.tsx`
- [Tamper review](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Tamper.tsx): `beehive-main/apps/web/src/pages/Tamper.tsx`
- [Forecasting](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Forecast.tsx): `beehive-main/apps/web/src/pages/Forecast.tsx`
- [Hive dashboard](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Dashboard.tsx): `beehive-main/apps/web/src/pages/Dashboard.tsx`
- [Batch records](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/pages/Batches.tsx): `beehive-main/apps/web/src/pages/Batches.tsx`
- [API client](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/web/src/lib/api.ts): `beehive-main/apps/web/src/lib/api.ts`

### Worker services

- [API router](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/index.ts): `beehive-main/apps/worker/src/index.ts`
- [Sessions and roles](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/auth.ts): `beehive-main/apps/worker/src/auth.ts`
- [Hive records](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/hives.ts): `beehive-main/apps/worker/src/hives.ts`
- [Scan handling](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/scans.ts): `beehive-main/apps/worker/src/scans.ts`
- [Batch records](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/batches.ts): `beehive-main/apps/worker/src/batches.ts`
- [Evidence documents](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/documents.ts): `beehive-main/apps/worker/src/documents.ts`
- [Oversight services](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/authority.ts): `beehive-main/apps/worker/src/authority.ts`
- [Proof verification](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/verify.ts): `beehive-main/apps/worker/src/verify.ts`

### Analysis engines

- [Scan analysis](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/scan-engine/src/index.ts): `beehive-main/packages/scan-engine/src/index.ts`
- [Forecast engine](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/scan-engine/src/forecast.ts): `beehive-main/packages/scan-engine/src/forecast.ts`
- [Risk assessment](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/risk-engine/src/index.ts): `beehive-main/packages/risk-engine/src/index.ts`

### Proof and records

- [Domain schemas](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/shared/src/index.ts): `beehive-main/packages/shared/src/index.ts`
- [Record proofs](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/apps/worker/src/proofs.ts): `beehive-main/apps/worker/src/proofs.ts`
- [Canonical hashing](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/shared/src/canonical.ts): `beehive-main/packages/shared/src/canonical.ts`
- [Blockchain client](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/blockchain/src/index.ts): `beehive-main/packages/blockchain/src/index.ts`
- [Registry interface](https://github.com/fayizzbanday/beehive.fsoc/blob/main/beehive-main/packages/blockchain/src/abi.ts): `beehive-main/packages/blockchain/src/abi.ts`

### Other components

- **Beekeeper**
- **Shopper**
- **Authority user**
- **Ethereum network**
- **Worker database**

## Connections

- Web routes → Video scan: routes to (evidence: `beehive-main/apps/web/src/App.tsx`)
- Web routes → Hive management: routes to (evidence: `beehive-main/apps/web/src/App.tsx`)
- Web routes → Batch creation: routes to (evidence: `beehive-main/apps/web/src/App.tsx`)
- Web routes → Public verification: routes to (evidence: `beehive-main/apps/web/src/App.tsx`)
- Web routes → Authority console: routes to (evidence: `beehive-main/apps/web/src/App.tsx`)
- Web routes → Tamper review: routes to (evidence: `beehive-main/apps/web/src/App.tsx`)
- Web routes → Forecasting: routes to (evidence: `beehive-main/apps/web/src/App.tsx`)
- Web routes → Hive dashboard: routes to (evidence: `beehive-main/apps/web/src/App.tsx`)
- Web routes → Batch records: routes to (evidence: `beehive-main/apps/web/src/App.tsx`)
- Beekeeper → Video scan: submits video
- Beekeeper → Hive management: manages colonies
- Beekeeper → Batch creation: records harvest
- Shopper → Public verification: scans jar
- Authority user → Authority console: reviews alerts
- Video scan → API client: requests scans (evidence: `beehive-main/apps/web/src/pages/Scan.tsx`)
- Hive management → API client: requests records (evidence: `beehive-main/apps/web/src/pages/Hives.tsx`)
- Batch creation → API client: submits batch (evidence: `beehive-main/apps/web/src/pages/BatchWizard.tsx`)
- Public verification → API client: requests proof (evidence: `beehive-main/apps/web/src/pages/Verify.tsx`)
- Authority console → API client: requests oversight (evidence: `beehive-main/apps/web/src/pages/Authority.tsx`)
- Tamper review → API client: requests alerts (evidence: `beehive-main/apps/web/src/pages/Tamper.tsx`)
- Forecasting → API client: requests forecast (evidence: `beehive-main/apps/web/src/pages/Forecast.tsx`)
- Hive dashboard → API client: requests summaries (evidence: `beehive-main/apps/web/src/pages/Dashboard.tsx`)
- Batch records → API client: requests batches (evidence: `beehive-main/apps/web/src/pages/Batches.tsx`)
- API client → API router: calls API
- API router → Sessions and roles: dispatches auth
- API router → Hive records: dispatches hive routes
- API router → Scan handling: dispatches scan routes
- API router → Batch records: dispatches batch routes
- API router → Evidence documents: dispatches documents
- API router → Oversight services: dispatches oversight
- API router → Proof verification: dispatches verification
- Scan handling → Scan analysis: analyzes frames
- Scan analysis → Risk assessment: uses classification (evidence: `beehive-main/packages/scan-engine/src/index.ts`)
- Forecasting → Forecast engine: renders forecast
- Batch records → Risk assessment: assesses metadata
- Scan handling → Worker database: stores scan
- Hive records → Worker database: stores hive
- Batch records → Worker database: stores batch
- Oversight services → Worker database: reads alerts
- Proof verification → Record proofs: checks proof
- Record proofs → Canonical hashing: hashes record
- Record proofs → Blockchain client: anchors record
- Proof verification → Blockchain client: reads anchor
- Blockchain client → Registry interface: uses ABI (evidence: `beehive-main/packages/blockchain/src/index.ts`)
- Blockchain client → Ethereum network: reads and writes
- Scan handling → Domain schemas: uses schemas
- Batch records → Domain schemas: uses schemas
- Risk assessment → Domain schemas: uses domain types (evidence: `beehive-main/packages/risk-engine/src/index.ts`)
