# sbezhuk/beebase-hive-service architecture

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

- Interactive diagram: https://gitdiagram.com/sbezhuk/beebase-hive-service
- Repository: https://github.com/sbezhuk/beebase-hive-service
- Video tour (about a minute): https://gitdiagram.com/sbezhuk/beebase-hive-service/video

## Overview

BeeBase Hive Service manages hive records and queen histories, and can assemble and render Pro-only hive reports. The main workflow is an authenticated HTTP request routed to a hive or queen handler, then an application service that enforces ownership and entitlement, calls repositories and relevant peer services, and returns a response. Hive deletion also cascades to dependent services. The report flow gathers hive, queen, inspection, harvest, and apiary data before PDF rendering. Wiring for unsampled subsystems follows the README and entry-point excerpts; uncertain call details are omitted.

Main entry points: [`internal/application/hive/service.go`](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/application/hive/service.go) (Hive use cases), [`internal/application/report/service.go`](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/application/report/service.go) (Report assembly), [`internal/application/queen/service.go`](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/application/queen/service.go) (Queen use cases), [`internal/transport/http/hive/handler.go`](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/transport/http/hive/handler.go) (Hive handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transport["HTTP transport"]
  node_router["HTTP router<br/>[router.go]"]
  node_hivehandler["Hive handlers<br/>[handler.go]"]
  node_queenhandler["Queen handlers<br/>[handler.go]"]
end

subgraph group_application["Application services"]
  node_hiveservice["Hive use cases<br/>[service.go]"]
  node_queenservice["Queen use cases<br/>[service.go]"]
  node_hivedomain["Hive model<br/>[hive.go]"]
  node_queendomain["Queen model<br/>[queen.go]"]
end

subgraph group_persistence["Persistence"]
  node_hiverepo["Hive repository<br/>[hive_repository.go]"]
  node_queenrepo["Queen repository"]
  node_postgres[("PostgreSQL<br/>[postgres.go]")]
end

subgraph group_integrations["Peer services"]
  node_apiaryclient["Apiary client<br/>[client.go]"]
  node_inspectionclient["Inspection client<br/>[client.go]"]
  node_harvestclient["Harvest client<br/>[client.go]"]
  node_mediaclient["Media client<br/>[client.go]"]
  node_subscriptionclient["Subscription client<br/>[client.go]"]
  node_notificationclient["Notification client<br/>[client.go]"]
end

subgraph group_reporting["Reporting"]
  node_reportservice["Report assembly<br/>[service.go]"]
  node_pdfrenderer["PDF renderer<br/>[renderer.go]"]
  node_pdfresult["PDF report"]
end

node_client(("API caller"))
node_apiaryservice["Apiary service"]
node_inspectionservice["Inspection service"]
node_harvestservice["Harvest service"]
node_mediaservice["Media service"]
node_subscriptionservice["Subscription service"]
node_notificationservice["Notification service"]

node_client -->|"sends request"| node_router
node_router -->|"routes hive requests"| node_hivehandler
node_router -->|"routes queen requests"| node_queenhandler
node_hivehandler -->|"invokes use cases"| node_hiveservice
node_queenhandler -->|"invokes use cases"| node_queenservice
node_hiveservice -->|"reads and writes"| node_hiverepo
node_hiveservice -->|"uses model"| node_hivedomain
node_hiveservice -->|"checks ownership"| node_apiaryclient
node_hiveservice -->|"checks entitlement"| node_subscriptionclient
node_hiveservice -->|"checks or deletes inspections"| node_inspectionclient
node_hiveservice -->|"deletes harvests"| node_harvestclient
node_hiveservice -->|"deletes media"| node_mediaclient
node_hiveservice -.->|"dispatches notices"| node_notificationclient
node_queenservice -->|"reads and writes"| node_queenrepo
node_queenservice -->|"checks hive ownership"| node_hiverepo
node_queenservice -->|"checks writability"| node_apiaryclient
node_queenservice -->|"checks entitlement"| node_subscriptionclient
node_queenservice -->|"uses model"| node_queendomain
node_hiverepo -->|"queries hive data"| node_postgres
node_queenrepo -->|"queries queen data"| node_postgres
node_apiaryclient -->|"calls API"| node_apiaryservice
node_inspectionclient -->|"calls API"| node_inspectionservice
node_harvestclient -->|"calls API"| node_harvestservice
node_mediaclient -->|"calls API"| node_mediaservice
node_subscriptionclient -->|"calls API"| node_subscriptionservice
node_notificationclient -.->|"calls API"| node_notificationservice
node_hivehandler -->|"assembles report"| node_reportservice
node_reportservice -->|"reads hive"| node_hiveservice
node_reportservice -->|"reads queen history"| node_queenservice
node_reportservice -->|"checks Pro access"| node_subscriptionclient
node_reportservice -->|"fetches report data"| node_inspectionclient
node_reportservice -->|"fetches report data"| node_harvestclient
node_reportservice -->|"fetches apiary details"| node_apiaryclient
node_hivehandler -->|"renders report"| node_pdfrenderer
node_pdfrenderer -->|"produces PDF"| node_pdfresult

click node_router "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/transport/http/router.go"
click node_hivehandler "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/transport/http/hive/handler.go"
click node_queenhandler "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/transport/http/queen/handler.go"
click node_hiveservice "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/application/hive/service.go"
click node_queenservice "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/application/queen/service.go"
click node_reportservice "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/application/report/service.go"
click node_hivedomain "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/domain/hive/hive.go"
click node_queendomain "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/domain/queen/queen.go"
click node_hiverepo "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/repository/postgres/hive_repository.go"
click node_queenrepo "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/repository/postgres/queen_repository.go"
click node_postgres "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/postgres/postgres.go"
click node_apiaryclient "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/apiaryclient/client.go"
click node_inspectionclient "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/inspectionclient/client.go"
click node_harvestclient "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/harvestclient/client.go"
click node_mediaclient "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/mediaclient/client.go"
click node_subscriptionclient "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/subscriptionclient/client.go"
click node_notificationclient "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/notificationclient/client.go"
click node_pdfrenderer "https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/report/pdf/renderer.go"

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_router,node_hivehandler,node_queenhandler toneBlue
class node_hiveservice,node_queenservice,node_hivedomain,node_queendomain toneAmber
class node_hiverepo,node_queenrepo,node_postgres,node_client,node_apiaryservice toneMint
class node_apiaryclient,node_inspectionclient,node_harvestclient,node_mediaclient,node_subscriptionclient,node_notificationclient toneRose
class node_reportservice,node_pdfrenderer,node_pdfresult,node_inspectionservice,node_harvestservice,node_mediaservice,node_subscriptionservice,node_notificationservice toneIndigo
```

## Components

### HTTP transport

- [HTTP router](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/transport/http/router.go): `internal/transport/http/router.go`
- [Hive handlers](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/transport/http/hive/handler.go): `internal/transport/http/hive/handler.go`
- [Queen handlers](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/transport/http/queen/handler.go): `internal/transport/http/queen/handler.go`

### Application services

- [Hive use cases](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/application/hive/service.go): `internal/application/hive/service.go`
- [Queen use cases](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/application/queen/service.go): `internal/application/queen/service.go`
- [Hive model](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/domain/hive/hive.go): `internal/domain/hive/hive.go`
- [Queen model](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/domain/queen/queen.go): `internal/domain/queen/queen.go`

### Persistence

- [Hive repository](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/repository/postgres/hive_repository.go): `internal/repository/postgres/hive_repository.go`
- [Queen repository](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/repository/postgres/queen_repository.go): `internal/repository/postgres/queen_repository.go`
- [PostgreSQL](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/postgres/postgres.go): `internal/platform/postgres/postgres.go`

### Peer services

- [Apiary client](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/apiaryclient/client.go): `internal/platform/apiaryclient/client.go`
- [Inspection client](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/inspectionclient/client.go): `internal/platform/inspectionclient/client.go`
- [Harvest client](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/harvestclient/client.go): `internal/platform/harvestclient/client.go`
- [Media client](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/mediaclient/client.go): `internal/platform/mediaclient/client.go`
- [Subscription client](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/subscriptionclient/client.go): `internal/platform/subscriptionclient/client.go`
- [Notification client](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/platform/notificationclient/client.go): `internal/platform/notificationclient/client.go`

### Reporting

- [Report assembly](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/application/report/service.go): `internal/application/report/service.go`
- [PDF renderer](https://github.com/sbezhuk/beebase-hive-service/blob/main/internal/report/pdf/renderer.go): `internal/report/pdf/renderer.go`
- **PDF report**

### Other components

- **API caller**
- **Apiary service**
- **Inspection service**
- **Harvest service**
- **Media service**
- **Subscription service**
- **Notification service**

## Connections

- API caller → HTTP router: sends request
- HTTP router → Hive handlers: routes hive requests
- HTTP router → Queen handlers: routes queen requests
- Hive handlers → Hive use cases: invokes use cases
- Queen handlers → Queen use cases: invokes use cases
- Hive use cases → Hive repository: reads and writes
- Hive use cases → Hive model: uses model
- Hive use cases → Apiary client: checks ownership
- Hive use cases → Subscription client: checks entitlement
- Hive use cases → Inspection client: checks or deletes inspections
- Hive use cases → Harvest client: deletes harvests
- Hive use cases → Media client: deletes media
- Hive use cases → Notification client: dispatches notices
- Queen use cases → Queen repository: reads and writes
- Queen use cases → Hive repository: checks hive ownership
- Queen use cases → Apiary client: checks writability
- Queen use cases → Subscription client: checks entitlement
- Queen use cases → Queen model: uses model
- Hive repository → PostgreSQL: queries hive data
- Queen repository → PostgreSQL: queries queen data
- Apiary client → Apiary service: calls API
- Inspection client → Inspection service: calls API
- Harvest client → Harvest service: calls API
- Media client → Media service: calls API
- Subscription client → Subscription service: calls API
- Notification client → Notification service: calls API
- Hive handlers → Report assembly: assembles report
- Report assembly → Hive use cases: reads hive
- Report assembly → Queen use cases: reads queen history
- Report assembly → Subscription client: checks Pro access
- Report assembly → Inspection client: fetches report data
- Report assembly → Harvest client: fetches report data
- Report assembly → Apiary client: fetches apiary details
- Hive handlers → PDF renderer: renders report
- PDF renderer → PDF report: produces PDF