# eltemsahy/warehouse-system architecture

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

- Interactive diagram: https://gitdiagram.com/eltemsahy/warehouse-system
- Repository: https://github.com/eltemsahy/warehouse-system

## Overview

This is a TypeScript/Express modular monolith for warehouse operations. The implemented workflow is an API request for catalog, location, or stock operations: routes validate input and invoke application services or use cases, which enforce domain rules and access repositories or the stock ledger. Inventory also supports idempotent writes, reliable event delivery, and a nightly integrity check. The admin frontend is an early-stage landing page, not a demonstrated operational client. Some subsystem wiring is unsampled, so uncertain relationships are omitted.

Main entry points: [`apps/api/src/app.ts`](https://github.com/eltemsahy/warehouse-system/blob/main/apps/api/src/app.ts) (Express app), [`modules/inventory/api/routes.ts`](https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/api/routes.ts) (Inventory routes), [`modules/catalog/api/routes.ts`](https://github.com/eltemsahy/warehouse-system/blob/main/modules/catalog/api/routes.ts) (Catalog routes), [`modules/catalog/application/item-service.ts`](https://github.com/eltemsahy/warehouse-system/blob/main/modules/catalog/application/item-service.ts) (Catalog services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API runtime"]
  node_server["Express app<br/>[app.ts]"]
end

subgraph group_master["Master data"]
  node_catalog_routes["Catalog routes<br/>[routes.ts]"]
  node_catalog_service["Catalog services<br/>[item-service.ts]"]
  node_catalog_store[("Catalog repository")]
  node_locations_routes["Location routes<br/>[routes.ts]"]
  node_locations_service["Location services"]
  node_locations_store[("Locations repository")]
end

subgraph group_inventory["Inventory operations"]
  node_inventory_routes["Inventory routes<br/>[routes.ts]"]
  node_adjust["Stock adjustment<br/>[adjust-stock.ts]"]
  node_transfer["Stock transfer<br/>[transfer-stock.ts]"]
  node_ledger[("Stock ledger<br/>[pg-stock-ledger.ts]")]
  node_ledger_audit["Ledger integrity"]
end

subgraph group_platform["Reliability services"]
  node_idempotency["Idempotency<br/>[idempotency.ts]"]
  node_outbox["Outbox relay<br/>[outbox-relay.ts]"]
  node_daily_job["Daily scheduler<br/>[daily-job.ts]"]
end

subgraph group_web["Admin frontend"]
  node_admin["Admin landing page<br/>[LandingPage.tsx]"]
  node_preview["Dashboard preview"]
  node_preview_data["Preview data<br/>[previewData.ts]"]
end

node_operator(("API caller"))

node_operator -->|"sends requests"| node_server
node_server -->|"mounts module"| node_catalog_routes
node_server -->|"mounts module"| node_locations_routes
node_server -->|"mounts module"| node_inventory_routes
node_server -->|"installs middleware"| node_idempotency
node_server -->|"creates relay"| node_outbox
node_server -->|"schedules check"| node_daily_job
node_catalog_routes -->|"invokes services"| node_catalog_service
node_catalog_service -->|"reads and writes"| node_catalog_store
node_locations_routes -->|"invokes services"| node_locations_service
node_locations_service -->|"reads and writes"| node_locations_store
node_inventory_routes -->|"executes adjustment"| node_adjust
node_inventory_routes -->|"executes transfer"| node_transfer
node_inventory_routes -->|"reads balance"| node_ledger
node_admin -.->|"renders preview"| node_preview
node_preview -->|"uses data"| node_preview_data

click node_server "https://github.com/eltemsahy/warehouse-system/blob/main/apps/api/src/app.ts"
click node_catalog_routes "https://github.com/eltemsahy/warehouse-system/blob/main/modules/catalog/api/routes.ts"
click node_catalog_service "https://github.com/eltemsahy/warehouse-system/blob/main/modules/catalog/application/item-service.ts"
click node_catalog_store "https://github.com/eltemsahy/warehouse-system/blob/main/modules/catalog/infrastructure/pg-catalog-repository.ts"
click node_locations_routes "https://github.com/eltemsahy/warehouse-system/blob/main/modules/locations/api/routes.ts"
click node_locations_service "https://github.com/eltemsahy/warehouse-system/blob/main/modules/locations/application/location-service.ts"
click node_locations_store "https://github.com/eltemsahy/warehouse-system/blob/main/modules/locations/infrastructure/pg-locations-repository.ts"
click node_inventory_routes "https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/api/routes.ts"
click node_adjust "https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/application/adjust-stock.ts"
click node_transfer "https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/application/transfer-stock.ts"
click node_ledger "https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/infrastructure/pg-stock-ledger.ts"
click node_ledger_audit "https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/application/check-ledger-integrity.ts"
click node_idempotency "https://github.com/eltemsahy/warehouse-system/blob/main/shared/http/idempotency.ts"
click node_outbox "https://github.com/eltemsahy/warehouse-system/blob/main/shared/events/outbox-relay.ts"
click node_daily_job "https://github.com/eltemsahy/warehouse-system/blob/main/shared/jobs/daily-job.ts"
click node_admin "https://github.com/eltemsahy/warehouse-system/blob/main/apps/web-admin/src/pages/LandingPage.tsx"
click node_preview "https://github.com/eltemsahy/warehouse-system/blob/main/apps/web-admin/src/features/landing/components/DashboardPreview.tsx"
click node_preview_data "https://github.com/eltemsahy/warehouse-system/blob/main/apps/web-admin/src/features/landing/data/previewData.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_server toneBlue
class node_catalog_routes,node_catalog_service,node_catalog_store,node_locations_routes,node_locations_service,node_locations_store toneAmber
class node_inventory_routes,node_adjust,node_transfer,node_ledger,node_ledger_audit,node_operator toneMint
class node_idempotency,node_outbox,node_daily_job toneRose
class node_admin,node_preview,node_preview_data toneIndigo
```

## Components

### API runtime

- [Express app](https://github.com/eltemsahy/warehouse-system/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`

### Master data

- [Catalog routes](https://github.com/eltemsahy/warehouse-system/blob/main/modules/catalog/api/routes.ts): `modules/catalog/api/routes.ts`
- [Catalog services](https://github.com/eltemsahy/warehouse-system/blob/main/modules/catalog/application/item-service.ts): `modules/catalog/application/item-service.ts`
- [Catalog repository](https://github.com/eltemsahy/warehouse-system/blob/main/modules/catalog/infrastructure/pg-catalog-repository.ts): `modules/catalog/infrastructure/pg-catalog-repository.ts`
- [Location routes](https://github.com/eltemsahy/warehouse-system/blob/main/modules/locations/api/routes.ts): `modules/locations/api/routes.ts`
- [Location services](https://github.com/eltemsahy/warehouse-system/blob/main/modules/locations/application/location-service.ts): `modules/locations/application/location-service.ts`
- [Locations repository](https://github.com/eltemsahy/warehouse-system/blob/main/modules/locations/infrastructure/pg-locations-repository.ts): `modules/locations/infrastructure/pg-locations-repository.ts`

### Inventory operations

- [Inventory routes](https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/api/routes.ts): `modules/inventory/api/routes.ts`
- [Stock adjustment](https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/application/adjust-stock.ts): `modules/inventory/application/adjust-stock.ts`
- [Stock transfer](https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/application/transfer-stock.ts): `modules/inventory/application/transfer-stock.ts`
- [Stock ledger](https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/infrastructure/pg-stock-ledger.ts): `modules/inventory/infrastructure/pg-stock-ledger.ts`
- [Ledger integrity](https://github.com/eltemsahy/warehouse-system/blob/main/modules/inventory/application/check-ledger-integrity.ts): `modules/inventory/application/check-ledger-integrity.ts`

### Reliability services

- [Idempotency](https://github.com/eltemsahy/warehouse-system/blob/main/shared/http/idempotency.ts): `shared/http/idempotency.ts`
- [Outbox relay](https://github.com/eltemsahy/warehouse-system/blob/main/shared/events/outbox-relay.ts): `shared/events/outbox-relay.ts`
- [Daily scheduler](https://github.com/eltemsahy/warehouse-system/blob/main/shared/jobs/daily-job.ts): `shared/jobs/daily-job.ts`

### Admin frontend

- [Admin landing page](https://github.com/eltemsahy/warehouse-system/blob/main/apps/web-admin/src/pages/LandingPage.tsx): `apps/web-admin/src/pages/LandingPage.tsx`
- [Dashboard preview](https://github.com/eltemsahy/warehouse-system/blob/main/apps/web-admin/src/features/landing/components/DashboardPreview.tsx): `apps/web-admin/src/features/landing/components/DashboardPreview.tsx`
- [Preview data](https://github.com/eltemsahy/warehouse-system/blob/main/apps/web-admin/src/features/landing/data/previewData.ts): `apps/web-admin/src/features/landing/data/previewData.ts`

### Other components

- **API caller**

## Connections

- API caller → Express app: sends requests (evidence: `README.md`)
- Express app → Catalog routes: mounts module (evidence: `apps/api/src/app.ts`)
- Express app → Location routes: mounts module (evidence: `apps/api/src/app.ts`)
- Express app → Inventory routes: mounts module (evidence: `apps/api/src/app.ts`)
- Express app → Idempotency: installs middleware (evidence: `apps/api/src/app.ts`)
- Express app → Outbox relay: creates relay (evidence: `apps/api/src/app.ts`)
- Express app → Daily scheduler: schedules check (evidence: `apps/api/src/app.ts`)
- Catalog routes → Catalog services: invokes services (evidence: `modules/catalog/api/routes.ts`)
- Catalog services → Catalog repository: reads and writes (evidence: `modules/catalog/application/item-service.ts`)
- Location routes → Location services: invokes services (evidence: `modules/locations/api/routes.ts`)
- Location services → Locations repository: reads and writes (evidence: `modules/locations/application/location-service.ts`)
- Inventory routes → Stock adjustment: executes adjustment (evidence: `modules/inventory/api/routes.ts`)
- Inventory routes → Stock transfer: executes transfer (evidence: `modules/inventory/api/routes.ts`)
- Inventory routes → Stock ledger: reads balance (evidence: `modules/inventory/api/routes.ts`)
- Admin landing page → Dashboard preview: renders preview
- Dashboard preview → Preview data: uses data (evidence: `apps/web-admin/src/features/landing/components/DashboardPreview.tsx`)
