# epic-breakfast-productions/openquartermaster architecture

> Architecture diagram of the GitHub repository epic-breakfast-productions/openquartermaster, 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/epic-breakfast-productions/openquartermaster
- Repository: https://github.com/epic-breakfast-productions/openquartermaster

## Overview

Open QuarterMaster is a modular inventory-management system: users manage what is stored where through the Base Station and Core API, with plugins adding specialized workflows. The Core API owns generic inventory, storage, checkout, identifiers, media, and history capabilities; Mongo-backed services persist domain records. The README documents the Base Station as the Core API frontend and plugins as extensions. Sampled code confirms storage-block search and persistence, PDF inventory-sheet retrieval, external-item lookup, MSS hardware control, and voice search. Other subsystem links reflect README capability descriptions; unsampled wiring is not inferred.

Main entry points: [`software/core/oqm-core-api`](https://github.com/epic-breakfast-productions/openquartermaster/tree/main/software/core/oqm-core-api) (Core API), [`software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/service/mongo/StorageBlockService.java`](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/service/mongo/StorageBlockService.java) (Storage blocks), [`software/core/oqm-core-base-station`](https://github.com/epic-breakfast-productions/openquartermaster/tree/main/software/core/oqm-core-base-station) (Inventory UI), [`software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/rest/search/StorageBlockSearch.java`](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/rest/search/StorageBlockSearch.java) (Storage search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core inventory"]
  node_api["Core API"]
  node_inventory["Inventory records"]
  node_storage["Storage blocks"]
  node_storage_search["Storage search"]
  node_checkout["Checkout records"]
  node_identifiers["Item identifiers"]
  node_media["Images and files<br/>[ImageCrud.java]"]
  node_history["Object history"]
  node_mongo[("MongoDB")]
end

subgraph group_station["Base Station"]
  node_station_ui["Inventory UI"]
  node_sheet_service["Inventory sheets"]
end

subgraph group_plugins["Extensions"]
  node_ext_search["External item search"]
  node_amazon["Amazon scraper"]
  node_mss_plugin["MSS controller"]
  node_voice["Voice search"]
end

subgraph group_hardware["MSS device"]
  node_mss_engine["MSS engine<br/>[MssEngine.h]"]
  node_mss_connector["MSS connector<br/>[MssConnector.h]"]
end

subgraph group_deployment["Deployment"]
  node_captain["Station Captain<br/>[oqm-captain.py]"]
  node_kubernetes["Kubernetes operator"]
end

node_operator(("Inventory user"))

node_operator -->|"manages inventory"| node_station_ui
node_station_ui -->|"uses frontend"| node_api
node_api -->|"dispatches inventory"| node_inventory
node_api -->|"dispatches storage"| node_storage
node_storage -->|"builds filters"| node_storage_search
node_storage -->|"reads and writes"| node_mongo
node_api -->|"dispatches checkout"| node_checkout
node_api -->|"dispatches identifiers"| node_identifiers
node_api -->|"dispatches media"| node_media
node_api -->|"tracks changes"| node_history
node_sheet_service -->|"fetches storage block"| node_api
node_station_ui -->|"submits search"| node_storage_search
node_ext_search -.->|"scrapes product page"| node_amazon
node_mss_plugin -->|"searches storage blocks"| node_api
node_voice -->|"searches inventory"| node_api
node_mss_engine -->|"polls commands"| node_mss_connector
node_captain -->|"manages host setup"| node_operator

click node_station_ui "https://github.com/epic-breakfast-productions/openquartermaster/tree/main/software/core/oqm-core-base-station"
click node_sheet_service "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-base-station/src/main/java/tech/ebp/oqm/core/baseStation/service/printout/StorageBlockInventorySheetService.java"
click node_api "https://github.com/epic-breakfast-productions/openquartermaster/tree/main/software/core/oqm-core-api"
click node_inventory "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/inventory/items/InventoryItemsCrud.java"
click node_storage "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/service/mongo/StorageBlockService.java"
click node_storage_search "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/rest/search/StorageBlockSearch.java"
click node_checkout "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/inventory/ItemCheckoutCrud.java"
click node_identifiers "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/identifiers/IdentifierEndpoints.java"
click node_media "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/media/ImageCrud.java"
click node_history "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/history/ObjectHistoryEvent.java"
click node_ext_search "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/plugins/external-item-search/src/main/java/tech/ebp/oqm/plugin/extItemSearch/service/extItemSearchService/ItemSearchService.java"
click node_amazon "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/plugins/external-item-search/temp/webPage/AmazonWebProductScrapeService.java"
click node_mss_plugin "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/plugins/mss-controller/mss-controller-plugin/src/main/java/tech/ebp/oqm/plugin/mssController/moduleInteraction/service/StorageBlockInteractionService.java"
click node_mss_engine "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/hardware/mss/mss/MssEngine.h"
click node_mss_connector "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/hardware/mss/mss/MssConnector.h"
click node_captain "https://github.com/epic-breakfast-productions/openquartermaster/blob/main/deployment/Single%20Host/Station-Captain/src/oqm-captain.py"
click node_kubernetes "https://github.com/epic-breakfast-productions/openquartermaster/tree/main/deployment/Kubernetes/operator"

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_api,node_inventory,node_storage,node_storage_search,node_checkout,node_identifiers,node_media,node_history,node_mongo,node_operator toneBlue
class node_station_ui,node_sheet_service toneAmber
class node_ext_search,node_amazon,node_mss_plugin,node_voice toneMint
class node_mss_engine,node_mss_connector toneRose
class node_captain,node_kubernetes toneIndigo
```

## Components

### Core inventory

- [Core API](https://github.com/epic-breakfast-productions/openquartermaster/tree/main/software/core/oqm-core-api): `software/core/oqm-core-api`
- [Inventory records](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/inventory/items/InventoryItemsCrud.java): `software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/inventory/items/InventoryItemsCrud.java`
- [Storage blocks](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/service/mongo/StorageBlockService.java): `software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/service/mongo/StorageBlockService.java`
- [Storage search](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/rest/search/StorageBlockSearch.java): `software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/rest/search/StorageBlockSearch.java`
- [Checkout records](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/inventory/ItemCheckoutCrud.java): `software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/inventory/ItemCheckoutCrud.java`
- [Item identifiers](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/identifiers/IdentifierEndpoints.java): `software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/identifiers/IdentifierEndpoints.java`
- [Images and files](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/media/ImageCrud.java): `software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/media/ImageCrud.java`
- [Object history](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/history/ObjectHistoryEvent.java): `software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/history/ObjectHistoryEvent.java`
- **MongoDB**

### Base Station

- [Inventory UI](https://github.com/epic-breakfast-productions/openquartermaster/tree/main/software/core/oqm-core-base-station): `software/core/oqm-core-base-station`
- [Inventory sheets](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/core/oqm-core-base-station/src/main/java/tech/ebp/oqm/core/baseStation/service/printout/StorageBlockInventorySheetService.java): `software/core/oqm-core-base-station/src/main/java/tech/ebp/oqm/core/baseStation/service/printout/StorageBlockInventorySheetService.java`

### Extensions

- [External item search](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/plugins/external-item-search/src/main/java/tech/ebp/oqm/plugin/extItemSearch/service/extItemSearchService/ItemSearchService.java): `software/plugins/external-item-search/src/main/java/tech/ebp/oqm/plugin/extItemSearch/service/extItemSearchService/ItemSearchService.java`
- [Amazon scraper](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/plugins/external-item-search/temp/webPage/AmazonWebProductScrapeService.java): `software/plugins/external-item-search/temp/webPage/AmazonWebProductScrapeService.java`
- [MSS controller](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/software/plugins/mss-controller/mss-controller-plugin/src/main/java/tech/ebp/oqm/plugin/mssController/moduleInteraction/service/StorageBlockInteractionService.java): `software/plugins/mss-controller/mss-controller-plugin/src/main/java/tech/ebp/oqm/plugin/mssController/moduleInteraction/service/StorageBlockInteractionService.java`
- **Voice search**

### MSS device

- [MSS engine](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/hardware/mss/mss/MssEngine.h): `hardware/mss/mss/MssEngine.h`
- [MSS connector](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/hardware/mss/mss/MssConnector.h): `hardware/mss/mss/MssConnector.h`

### Deployment

- [Station Captain](https://github.com/epic-breakfast-productions/openquartermaster/blob/main/deployment/Single%20Host/Station-Captain/src/oqm-captain.py): `deployment/Single Host/Station-Captain/src/oqm-captain.py`
- [Kubernetes operator](https://github.com/epic-breakfast-productions/openquartermaster/tree/main/deployment/Kubernetes/operator): `deployment/Kubernetes/operator`

### Other components

- **Inventory user**

## Connections

- Inventory user → Inventory UI: manages inventory
- Inventory UI → Core API: uses frontend
- Core API → Inventory records: dispatches inventory
- Core API → Storage blocks: dispatches storage
- Storage blocks → Storage search: builds filters
- Storage blocks → MongoDB: reads and writes
- Core API → Checkout records: dispatches checkout
- Core API → Item identifiers: dispatches identifiers
- Core API → Images and files: dispatches media
- Core API → Object history: tracks changes
- Inventory sheets → Core API: fetches storage block
- Inventory UI → Storage search: submits search
- External item search → Amazon scraper: scrapes product page
- MSS controller → Core API: searches storage blocks
- Voice search → Core API: searches inventory
- MSS engine → MSS connector: polls commands
- Station Captain → Inventory user: manages host setup