# sbezhuk/beebase-inspection-service architecture

> Architecture diagram of the GitHub repository sbezhuk/beebase-inspection-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-inspection-service
- Repository: https://github.com/sbezhuk/beebase-inspection-service

## Overview

BeeBase Inspection Service records and serves hive inspections. A beekeeper’s authenticated HTTP request is routed to inspection handlers, which validate input and invoke application use cases. Creation and updates verify hive writability; image references are checked with media-service, and inspection data is persisted in PostgreSQL. The service also exposes filtered listings, assessment and health/report endpoints, hive-status data for other services, and internal cleanup operations. Wiring and core use cases are sampled; several endpoint behaviors are documented in the README and router but their full implementations were not inspected.

Main entry points: [`internal/application/inspection/service.go`](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/application/inspection/service.go) (Inspection service), [`internal/transport/http/router.go`](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/transport/http/router.go) (HTTP router), [`internal/transport/http/inspection/handler.go`](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/transport/http/inspection/handler.go) (Inspection handlers), [`internal/platform/notificationclient/client.go`](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/platform/notificationclient/client.go) (Reminder cleanup client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transport["HTTP transport"]
  node_router["HTTP router<br/>[router.go]"]
  node_inspection_handler["Inspection handlers<br/>[handler.go]"]
  node_report_handler["Health/report handlers<br/>[report.go]"]
  node_health_routes["Health/readiness<br/>[health.go]"]
end

subgraph group_application["Inspection use cases"]
  node_app_service["Inspection service<br/>[service.go]"]
  node_domain_model["Inspection domain<br/>[inspection.go]"]
  node_assessment["Assessment rules<br/>[assessment.go]"]
  node_inspection_repo["Repository port<br/>[repository.go]"]
end

subgraph group_persistence["Inspection storage"]
  node_pg_repo["Postgres repository"]
  node_postgres[("PostgreSQL")]
end

subgraph group_integrations["Peer integrations"]
  node_hive_client["Hive client<br/>[client.go]"]
  node_media_client["Media client<br/>[client.go]"]
  node_notification_client["Reminder cleanup client<br/>[client.go]"]
end

node_beekeeper(("Beekeeper/client"))
node_hive_service["Hive service"]
node_media_service["Media service"]
node_notification_service["Notification service"]
node_auth_service["Auth JWKS"]
node_redis[("Session Redis")]
node_peer_services["Hive/statistics peers"]

node_beekeeper -->|"sends request"| node_router
node_router -->|"verifies tokens"| node_auth_service
node_router -->|"checks revocation"| node_redis
node_router -->|"dispatches routes"| node_inspection_handler
node_router -->|"dispatches health"| node_health_routes
node_inspection_handler -->|"calls use cases"| node_app_service
node_report_handler -->|"requests report data"| node_app_service
node_app_service -->|"uses repository"| node_inspection_repo
node_inspection_repo -->|"implemented by"| node_pg_repo
node_pg_repo -->|"reads/writes"| node_postgres
node_app_service -->|"verifies hive"| node_hive_client
node_hive_client -->|"checks ownership/writability"| node_hive_service
node_app_service -->|"verifies/deletes media"| node_media_client
node_media_client -->|"checks/deletes media"| node_media_service
node_app_service -->|"validates assessment"| node_assessment
node_app_service -->|"creates/updates"| node_domain_model
node_inspection_handler -->|"cleans reminders"| node_notification_client
node_app_service -->|"cleans hive reminders"| node_notification_client
node_notification_client -->|"sends cleanup"| node_notification_service
node_peer_services -.->|"calls internal endpoints"| node_router
node_health_routes -->|"checks readiness"| node_postgres

click node_router "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/transport/http/router.go"
click node_inspection_handler "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/transport/http/inspection/handler.go"
click node_report_handler "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/transport/http/inspection/report.go"
click node_health_routes "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/transport/http/health.go"
click node_app_service "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/application/inspection/service.go"
click node_domain_model "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/domain/inspection/inspection.go"
click node_assessment "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/domain/inspection/assessment.go"
click node_inspection_repo "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/domain/inspection/repository.go"
click node_pg_repo "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/repository/postgres/inspection_repository.go"
click node_postgres "https://github.com/sbezhuk/beebase-inspection-service/blob/main/migrations/000001_create_inspections_table.up.sql"
click node_hive_client "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/platform/hiveclient/client.go"
click node_media_client "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/platform/mediaclient/client.go"
click node_notification_client "https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/platform/notificationclient/client.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_inspection_handler,node_report_handler,node_health_routes,node_beekeeper toneBlue
class node_app_service,node_domain_model,node_assessment,node_inspection_repo,node_redis toneAmber
class node_pg_repo,node_postgres toneMint
class node_hive_client,node_media_client,node_notification_client toneRose
class node_hive_service,node_media_service,node_notification_service,node_auth_service,node_peer_services toneIndigo
```

## Components

### HTTP transport

- [HTTP router](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/transport/http/router.go): `internal/transport/http/router.go`
- [Inspection handlers](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/transport/http/inspection/handler.go): `internal/transport/http/inspection/handler.go`
- [Health/report handlers](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/transport/http/inspection/report.go): `internal/transport/http/inspection/report.go`
- [Health/readiness](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/transport/http/health.go): `internal/transport/http/health.go`

### Inspection use cases

- [Inspection service](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/application/inspection/service.go): `internal/application/inspection/service.go`
- [Inspection domain](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/domain/inspection/inspection.go): `internal/domain/inspection/inspection.go`
- [Assessment rules](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/domain/inspection/assessment.go): `internal/domain/inspection/assessment.go`
- [Repository port](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/domain/inspection/repository.go): `internal/domain/inspection/repository.go`

### Inspection storage

- [Postgres repository](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/repository/postgres/inspection_repository.go): `internal/repository/postgres/inspection_repository.go`
- [PostgreSQL](https://github.com/sbezhuk/beebase-inspection-service/blob/main/migrations/000001_create_inspections_table.up.sql): `migrations/000001_create_inspections_table.up.sql`

### Peer integrations

- [Hive client](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/platform/hiveclient/client.go): `internal/platform/hiveclient/client.go`
- [Media client](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/platform/mediaclient/client.go): `internal/platform/mediaclient/client.go`
- [Reminder cleanup client](https://github.com/sbezhuk/beebase-inspection-service/blob/main/internal/platform/notificationclient/client.go): `internal/platform/notificationclient/client.go`

### Other components

- **Beekeeper/client**
- **Hive service**
- **Media service**
- **Notification service**
- **Auth JWKS**
- **Session Redis**
- **Hive/statistics peers**

## Connections

- Beekeeper/client → HTTP router: sends request
- HTTP router → Auth JWKS: verifies tokens
- HTTP router → Session Redis: checks revocation
- HTTP router → Inspection handlers: dispatches routes
- HTTP router → Health/readiness: dispatches health
- Inspection handlers → Inspection service: calls use cases
- Health/report handlers → Inspection service: requests report data
- Inspection service → Repository port: uses repository
- Repository port → Postgres repository: implemented by
- Postgres repository → PostgreSQL: reads/writes
- Inspection service → Hive client: verifies hive
- Hive client → Hive service: checks ownership/writability
- Inspection service → Media client: verifies/deletes media
- Media client → Media service: checks/deletes media
- Inspection service → Assessment rules: validates assessment
- Inspection service → Inspection domain: creates/updates
- Inspection handlers → Reminder cleanup client: cleans reminders
- Inspection service → Reminder cleanup client: cleans hive reminders
- Reminder cleanup client → Notification service: sends cleanup
- Hive/statistics peers → HTTP router: calls internal endpoints
- Health/readiness → PostgreSQL: checks readiness