# khinya-khinev/receiving-service architecture

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

- Interactive diagram: https://gitdiagram.com/khinya-khinev/receiving-service
- Repository: https://github.com/khinya-khinev/receiving-service

## Overview

This is a warehouse goods-receiving backend. Managers maintain advance shipping notices (ASNs) and open or close goods receipts; workers join a receipt, scan handling units and contents, and complete their sessions. Receipt closure supports discrepancy reporting, while completed worker sessions support inventory put-away integration. The graph captures documented capabilities and source-visible calls; several API routes, event-listener bindings, and persistence details are represented only at subsystem level because their wiring was not shown in the excerpts.

Main entry points: [`src/main/java/com/waregang/receiving_service/receiving_process/application/ports`](https://github.com/khinya-khinev/receiving-service/tree/main/src/main/java/com/waregang/receiving_service/receiving_process/application/ports) (Receiving ports), [`src/main/java/com/waregang/receiving_service/receiving_process/application/ReceivingProcessService.java`](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/application/ReceivingProcessService.java) (Scanning sessions), [`src/main/java/com/waregang/receiving_service/receiving_process/application/GoodsReceiptService.java`](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/application/GoodsReceiptService.java) (Receipt lifecycle), [`src/main/java/com/waregang/receiving_service/integration/discrepancies_report/application/DiscrepanciesReportService.java`](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/integration/discrepancies_report/application/DiscrepanciesReportService.java) (Discrepancy calculation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_asn["ASN management"]
  node_asn_api["ASN API"]
  node_asn_service["ASN service"]
  node_asn_model["ASN records"]
end

subgraph group_receiving["Receiving execution"]
  node_receipt_api["Receipt API"]
  node_worker_api["Worker API"]
  node_receipt_service["Receipt lifecycle"]
  node_session_service["Scanning sessions"]
  node_session_model["Session state"]
  node_receipt_ports["Receiving ports"]
  node_asn_provider["ASN lookup adapter"]
end

subgraph group_storage["Persistence"]
  node_asn_repos[("ASN repositories")]
  node_receipt_store[("Receipt storage")]
  node_session_store[("Session storage")]
end

subgraph group_integration["Downstream integrations"]
  node_discrepancy_service["Discrepancy calculation"]
  node_discrepancy_adapter["Report Kafka adapter"]
  node_putaway_service["Put-away integration"]
  node_putaway_adapter["Inventory Kafka adapter"]
end

node_manager(("Manager"))
node_worker(("Warehouse worker"))
node_warehouse_system(("Downstream warehouse systems"))

node_manager -->|"manages ASNs"| node_asn_api
node_asn_api -->|"routes requests"| node_asn_service
node_asn_service -->|"reads and writes"| node_asn_repos
node_asn_service -->|"maps ASN"| node_asn_model
node_manager -.->|"starts receipts"| node_receipt_api
node_receipt_api -.->|"routes receipt actions"| node_receipt_service
node_worker -->|"scans goods"| node_worker_api
node_worker_api -->|"routes scan actions"| node_session_service
node_session_service -->|"checks ASN"| node_asn_provider
node_session_service -->|"uses repositories"| node_receipt_ports
node_session_service -->|"updates session"| node_session_model
node_receipt_service -->|"uses repositories"| node_receipt_ports
node_receipt_service -->|"loads ASN details"| node_asn_provider
node_receipt_ports -.->|"persists receipts"| node_receipt_store
node_receipt_ports -.->|"persists sessions"| node_session_store
node_asn_provider -.->|"uses ASN lookup"| node_asn_service
node_receipt_service -.->|"publishes closure event"| node_discrepancy_service
node_discrepancy_service -->|"reads expected quantities"| node_asn_repos
node_discrepancy_service -->|"reads received quantities"| node_receipt_ports
node_discrepancy_service -->|"sends report"| node_discrepancy_adapter
node_session_service -.->|"signals session completion"| node_putaway_service
node_putaway_service -->|"reads received units"| node_receipt_ports
node_putaway_service -->|"forwards put-away request"| node_putaway_adapter
node_discrepancy_adapter -.->|"publishes report"| node_warehouse_system
node_putaway_adapter -.->|"publishes put-away"| node_warehouse_system

click node_asn_api "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/advanced_shipping_notice/api/AdvancedShippingNoticeController.java"
click node_asn_service "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/advanced_shipping_notice/application/AdvancedShippingNoticeService.java"
click node_asn_model "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/advanced_shipping_notice/domain/model/AdvancedShippingNoticeJpa.java"
click node_asn_repos "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/advanced_shipping_notice/infrastructure/jpa_repositories/AdvancedShippingNoticeRepositoryJpa.java"
click node_receipt_api "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/api/GoodsReceiptController.java"
click node_worker_api "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/api/ReceivingProcessController.java"
click node_receipt_service "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/application/GoodsReceiptService.java"
click node_session_service "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/application/ReceivingProcessService.java"
click node_session_model "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/domain/model/WorkerReceivingSession.java"
click node_receipt_ports "https://github.com/khinya-khinev/receiving-service/tree/main/src/main/java/com/waregang/receiving_service/receiving_process/application/ports"
click node_receipt_store "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/infrastructure/adapters/GoodsReceiptJpaRepoAdapter.java"
click node_session_store "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/infrastructure/adapters/WorkerReceivingSessionJpaRepoAdapter.java"
click node_asn_provider "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/infrastructure/AsnInfoProviderAdapter.java"
click node_discrepancy_service "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/integration/discrepancies_report/application/DiscrepanciesReportService.java"
click node_discrepancy_adapter "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/integration/discrepancies_report/infrastructure/KafkaDiscrepanciesReportAdapter.java"
click node_putaway_service "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/integration/putaway/application/InventoryIntegrationService.java"
click node_putaway_adapter "https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/integration/putaway/infrastrusture/KafkaInventoryAdapter.java"

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_asn_api,node_asn_service,node_asn_model toneBlue
class node_receipt_api,node_worker_api,node_receipt_service,node_session_service,node_session_model,node_receipt_ports,node_asn_provider toneAmber
class node_asn_repos,node_receipt_store,node_session_store toneMint
class node_discrepancy_service,node_discrepancy_adapter,node_putaway_service,node_putaway_adapter,node_worker toneRose
class node_manager,node_warehouse_system toneIndigo
```

## Components

### ASN management

- [ASN API](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/advanced_shipping_notice/api/AdvancedShippingNoticeController.java): `src/main/java/com/waregang/receiving_service/advanced_shipping_notice/api/AdvancedShippingNoticeController.java`
- [ASN service](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/advanced_shipping_notice/application/AdvancedShippingNoticeService.java): `src/main/java/com/waregang/receiving_service/advanced_shipping_notice/application/AdvancedShippingNoticeService.java`
- [ASN records](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/advanced_shipping_notice/domain/model/AdvancedShippingNoticeJpa.java): `src/main/java/com/waregang/receiving_service/advanced_shipping_notice/domain/model/AdvancedShippingNoticeJpa.java`

### Receiving execution

- [Receipt API](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/api/GoodsReceiptController.java): `src/main/java/com/waregang/receiving_service/receiving_process/api/GoodsReceiptController.java`
- [Worker API](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/api/ReceivingProcessController.java): `src/main/java/com/waregang/receiving_service/receiving_process/api/ReceivingProcessController.java`
- [Receipt lifecycle](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/application/GoodsReceiptService.java): `src/main/java/com/waregang/receiving_service/receiving_process/application/GoodsReceiptService.java`
- [Scanning sessions](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/application/ReceivingProcessService.java): `src/main/java/com/waregang/receiving_service/receiving_process/application/ReceivingProcessService.java`
- [Session state](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/domain/model/WorkerReceivingSession.java): `src/main/java/com/waregang/receiving_service/receiving_process/domain/model/WorkerReceivingSession.java`
- [Receiving ports](https://github.com/khinya-khinev/receiving-service/tree/main/src/main/java/com/waregang/receiving_service/receiving_process/application/ports): `src/main/java/com/waregang/receiving_service/receiving_process/application/ports`
- [ASN lookup adapter](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/infrastructure/AsnInfoProviderAdapter.java): `src/main/java/com/waregang/receiving_service/receiving_process/infrastructure/AsnInfoProviderAdapter.java`

### Persistence

- [ASN repositories](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/advanced_shipping_notice/infrastructure/jpa_repositories/AdvancedShippingNoticeRepositoryJpa.java): `src/main/java/com/waregang/receiving_service/advanced_shipping_notice/infrastructure/jpa_repositories/AdvancedShippingNoticeRepositoryJpa.java`
- [Receipt storage](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/infrastructure/adapters/GoodsReceiptJpaRepoAdapter.java): `src/main/java/com/waregang/receiving_service/receiving_process/infrastructure/adapters/GoodsReceiptJpaRepoAdapter.java`
- [Session storage](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/receiving_process/infrastructure/adapters/WorkerReceivingSessionJpaRepoAdapter.java): `src/main/java/com/waregang/receiving_service/receiving_process/infrastructure/adapters/WorkerReceivingSessionJpaRepoAdapter.java`

### Downstream integrations

- [Discrepancy calculation](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/integration/discrepancies_report/application/DiscrepanciesReportService.java): `src/main/java/com/waregang/receiving_service/integration/discrepancies_report/application/DiscrepanciesReportService.java`
- [Report Kafka adapter](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/integration/discrepancies_report/infrastructure/KafkaDiscrepanciesReportAdapter.java): `src/main/java/com/waregang/receiving_service/integration/discrepancies_report/infrastructure/KafkaDiscrepanciesReportAdapter.java`
- [Put-away integration](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/integration/putaway/application/InventoryIntegrationService.java): `src/main/java/com/waregang/receiving_service/integration/putaway/application/InventoryIntegrationService.java`
- [Inventory Kafka adapter](https://github.com/khinya-khinev/receiving-service/blob/main/src/main/java/com/waregang/receiving_service/integration/putaway/infrastrusture/KafkaInventoryAdapter.java): `src/main/java/com/waregang/receiving_service/integration/putaway/infrastrusture/KafkaInventoryAdapter.java`

### Other components

- **Manager**
- **Warehouse worker**
- **Downstream warehouse systems**

## Connections

- Manager → ASN API: manages ASNs
- ASN API → ASN service: routes requests (evidence: `src/main/java/com/waregang/receiving_service/advanced_shipping_notice/api/AdvancedShippingNoticeController.java`)
- ASN service → ASN repositories: reads and writes (evidence: `src/main/java/com/waregang/receiving_service/advanced_shipping_notice/application/AdvancedShippingNoticeService.java`)
- ASN service → ASN records: maps ASN (evidence: `src/main/java/com/waregang/receiving_service/advanced_shipping_notice/application/AdvancedShippingNoticeService.java`)
- Manager → Receipt API: starts receipts
- Receipt API → Receipt lifecycle: routes receipt actions (evidence: `src/main/java/com/waregang/receiving_service/receiving_process/api/GoodsReceiptController.java`)
- Warehouse worker → Worker API: scans goods
- Worker API → Scanning sessions: routes scan actions (evidence: `src/main/java/com/waregang/receiving_service/receiving_process/api/ReceivingProcessController.java`)
- Scanning sessions → ASN lookup adapter: checks ASN (evidence: `src/main/java/com/waregang/receiving_service/receiving_process/application/ReceivingProcessService.java`)
- Scanning sessions → Receiving ports: uses repositories (evidence: `src/main/java/com/waregang/receiving_service/receiving_process/application/ReceivingProcessService.java`)
- Scanning sessions → Session state: updates session (evidence: `src/main/java/com/waregang/receiving_service/receiving_process/application/ReceivingProcessService.java`)
- Receipt lifecycle → Receiving ports: uses repositories (evidence: `src/main/java/com/waregang/receiving_service/receiving_process/application/GoodsReceiptService.java`)
- Receipt lifecycle → ASN lookup adapter: loads ASN details (evidence: `src/main/java/com/waregang/receiving_service/receiving_process/application/GoodsReceiptService.java`)
- Receiving ports → Receipt storage: persists receipts
- Receiving ports → Session storage: persists sessions (evidence: `src/main/java/com/waregang/receiving_service/receiving_process/infrastructure/adapters/WorkerReceivingSessionJpaRepoAdapter.java`)
- ASN lookup adapter → ASN service: uses ASN lookup
- Receipt lifecycle → Discrepancy calculation: publishes closure event
- Discrepancy calculation → ASN repositories: reads expected quantities (evidence: `src/main/java/com/waregang/receiving_service/integration/discrepancies_report/application/DiscrepanciesReportService.java`)
- Discrepancy calculation → Receiving ports: reads received quantities (evidence: `src/main/java/com/waregang/receiving_service/integration/discrepancies_report/application/DiscrepanciesReportService.java`)
- Discrepancy calculation → Report Kafka adapter: sends report (evidence: `src/main/java/com/waregang/receiving_service/integration/discrepancies_report/application/DiscrepanciesReportService.java`)
- Scanning sessions → Put-away integration: signals session completion
- Put-away integration → Receiving ports: reads received units (evidence: `src/main/java/com/waregang/receiving_service/integration/putaway/application/InventoryIntegrationService.java`)
- Put-away integration → Inventory Kafka adapter: forwards put-away request (evidence: `src/main/java/com/waregang/receiving_service/integration/putaway/application/InventoryIntegrationService.java`)
- Report Kafka adapter → Downstream warehouse systems: publishes report
- Inventory Kafka adapter → Downstream warehouse systems: publishes put-away
