Warehaus

Warehouse intelligence, powered by Elasticsearch

Search, monitor, and reason about millions of SKUs across every warehouse in milliseconds.

Live demo ·API. OpenAPI · Architecture · Report a bug

---

Why Warehaus?

Most inventory dashboards are glorified spreadsheets — slow to search, blind to anomalies, and useless when you actually need an answer. Warehaus is different. It treats your warehouse like a search problem, an analytics problem, and an alerting problem all at once — because that's what it actually is.

Built on Elasticsearch, Warehaus gives operations teams a single place to:

• Find anything across millions of SKUs with typo-tolerant, semantic search
• See what's wrong with real-time anomaly detection on stock movement
• Ask questions in plain English and get instant answers
• Visualize inventory geographically across every warehouse in your network

Think Algolia for inventory — but with the analytical power of Kibana baked in.

---

Screenshots

Dashboard — search, KPIs, charts, alerts, inventory

The dashboard at / ties every Elasticsearch capability into one view: a typo-tolerant search bar with completion-suggester autocomplete, four KPI tiles backed by metric aggregations, a 12-month date_histogram of stock movements, a 7-day anomaly chart driven by moving_fn pipeline aggregations, a terms-aggregation bar chart of stock by category, an active-alerts panel pulled from /api/anomalies, and a paginated product inventory.

Warehouse Map — geospatial view

The /map view renders each warehouse from a geo_point field on Leaflet/OpenStreetMap. Pin radius scales with the total stock value at that location (a sum aggregation on price * quantity), and the KPI tiles up top show per-warehouse SKUs and utilization. Optional geo_bounding_box filters narrow the result set to whatever's currently in the viewport.

---

Features

1. Smart search with typo tolerance and autocomplete

• multi_match with fuzziness: AUTO across name, description, category, sku, and tags
• Synonym filter at search time (drill ⇄ power tool, ppe ⇄ safety gear, box ⇄ carton, …)
• search_as_you_type field on name for instant prefix matches
• completion suggester powering the dropdown
• Term suggester for "did you mean" repair
• Relevance scoring exposed in the response so the UI can sort or weight as needed

2. Faceted filters with live counts

• terms aggregations on category, warehouse, and stock status
• range aggregation on price
• post_filter keeps facet counts broad while results narrow

3. KPI stat cards

• value_count (total SKUs), Painless sum of price * quantity (total stock value), cardinality (active warehouses), filter agg (low / out-of-stock count)
• Update live as filters apply

4. Anomaly alerts panel

• 30-day rolling baseline per SKU via date_histogram + moving_fn pipeline aggs
• Flags any 24-hour bucket exceeding mean + 2σ
• Returns enriched alerts (SKU, name, warehouse, sigma distance, severity)

5. Natural-language query chips

• POST /api/nl/query translates a small library of intents (out of stock in <city>, low stock <category>, demand spikes this week, overstocked raw materials, …) into ES DSL
• Endpoint returns both the generated DSL and the results so the UI can show its work

6. Geospatial warehouse map

• geo_point mapping + geo_bounding_box queries
• Per-warehouse stock-value rollups via terms + Painless sum aggregations
• Leaflet/OSM tile layer, no vendor key required

7. Vector / semantic similarity (optional but high-impact)

• dense_vector(384, cosine) field on warehaus-products
• 384-dim embeddings computed at ingest time by sentence-transformers/all-MiniLM-L6-v2
• GET /api/similar/:sku runs a kNN query, optionally combined with BM25 via reciprocal-rank fusion (hybrid retrieval)
• Falls back to more_like_this if embeddings haven't been generated

---

Tech stack

Layer	Tech	Why
Search & analytics	Elasticsearch 8.13	Full-text, aggregations, geo, vector search in one engine
API	Node.js 20 + Fastify	Low-overhead, schema-first HTTP layer with built-in OpenAPI
Frontend	Next.js 14 + Tailwind	App Router, fast DX, single-file standalone deploys
Charts	Recharts	Production-grade charting that plays well with React
Map	Leaflet + OpenStreetMap	No API keys, no vendor lock-in
Data ingest	Python 3.11 + Faker	Easy dummy-data generation + first-class ES client
Embeddings (optional)	sentence-transformers	Off-the-shelf 384-dim model for semantic search
Container	Docker Compose	One command to run everything
CI/CD	GitLab CI	Multi-stage pipeline with build, test, publish, manual deploy

---

Quick start

Get Warehaus running locally in under two minutes.

Prerequisites

• Docker and Docker Compose
• 4 GB RAM available for Elasticsearch
• Node.js 20+ and Python 3.11+ (only if running services outside Docker)

Run it

git clone https://github.com/remoterise-work/warehaus
cd warehaus
docker compose up -d --build elasticsearch kibana api frontend

That's it. Wait ~30 s for Elasticsearch to go green, then seed the data:

docker compose --profile seed run --rm ingest seed

Open the apps:

URL	What lives there
http://localhost:3000	Warehaus dashboard + map
http://localhost:4000/docs	OpenAPI / Swagger UI for the API
http://localhost:5601	Kibana, against the same cluster
http://localhost:9200	Elasticsearch HTTP endpoint

Shorthand for everything:

make up      # build + start stack
make seed    # load dummy data
make logs    # tail logs
make down    # stop
make clean   # stop + remove the ES volume

Semantic search (optional)

ENABLE_EMBEDDINGS=true docker compose --profile seed run --rm \
  -e ENABLE_EMBEDDINGS=true ingest seed

This installs sentence-transformers lazily, generates 384-dim embeddings for every product, and indexes them into the embedding field. After seeding, GET /api/similar/SKU-0001 returns kNN-ranked neighbours.

---

Repo layout

warehaus/
├─ backend/              # Fastify + Elasticsearch REST API
│  ├─ src/
│  │  ├─ routes/         # one file per feature (search, facets, stats, anomalies, nl-query, warehouses, vector, products)
│  │  ├─ lib/es-client.js
│  │  ├─ config.js
│  │  └─ server.js
│  ├─ openapi.yaml       # snapshot of the live spec at /docs
│  └─ Dockerfile
├─ frontend/             # Next.js 14 + Tailwind
│  └─ src/
│     ├─ app/            # / (dashboard) and /map (Leaflet)
│     ├─ components/     # StatCard, MovementChart, AnomalyChart, AlertsPanel, …
│     └─ lib/api.js
├─ data-ingest/          # Python CLI — generates dummy data + bulk-indexes it
│  └─ src/
│     ├─ cli.py
│     ├─ generators.py
│     ├─ mappings.py
│     └─ embeddings.py
├─ docs/
│  ├─ architecture.md
│  └─ screenshots/
│     ├─ dashboard.png
│     └─ warehouse-map.png
├─ docker-compose.yml
├─ .gitlab-ci.yml
├─ Makefile
└─ README.md

See docs/architecture.md for the deep dive on index design, request flow, and what each Elasticsearch feature maps to.

---

API reference

A few highlights — the full, always-current OpenAPI doc lives at http://localhost:4000/docs; an offline snapshot is at backend/openapi.yaml.

Search products

GET /api/search?q=cordles+dril&warehouse=Karachi%20Central&status=low_stock

{
  "took": 24,
  "total": 27,
  "results": [
    {
      "sku": "SKU-0042",
      "name": "Cordless Hammer Drill Pro",
      "warehouse": "Karachi Central",
      "quantity": 18,
      "status": "low_stock",
      "score": 12.4,
      "highlight": { "name": ["<mark>Cordless</mark> Hammer <mark>Drill</mark> Pro"] }
    }
  ],
  "facets": {
    "category": [{ "key": "Power Tools", "count": 12 }, { "key": "Hand Tools", "count": 6 }],
    "warehouse": [{ "key": "Karachi Central", "count": 8 }]
  },
  "suggest": { "did_you_mean": "cordless drill", "autocomplete": ["Cordless Hammer Drill", "Cordless Drill XL"] }
}

Ask in natural language

POST /api/nl/query
Content-Type: application/json

{ "question": "out of stock in Karachi" }

Find similar products

GET /api/similar/SKU-0042?k=5&hybrid=true

Anomaly alerts

GET /api/anomalies?sigma=2

---

Roadmap

• Full-text + faceted search across products and warehouses
• Real-time anomaly detection on stock movement
• Geospatial warehouse map
• Natural language query chips
• Vector / semantic similarity (with hybrid RRF + lexical fallback)
• Forecasting with Elasticsearch ML jobs
• Multi-tenant SaaS deployment with per-client indices
• Mobile app for warehouse floor scanning
• Slack / Teams integration for alert delivery

---

Why I built this

I'm a backend developer with years of experience building data replication and warehouse-adjacent systems at scale. After working on multi-cloud disaster recovery, change data capture pipelines, and inventory sync platforms, I kept seeing the same gap: operations teams have plenty of data, but no fast, intelligent way to interrogate it.

Warehaus is my answer — a portfolio piece that combines what I've learned about search, distributed systems, and warehouse operations into a single, opinionated product.

If you're hiring for backend or platform engineering roles, this repo is a good representation of how I think about building systems. Let's talk:

• LinkedIn
• Portfolio
• Dureforce
• Remoterise

---

Contributing

Issues and PRs welcome. Please open an issue first for any non-trivial change so we can align on the approach.

git clone https://github.com/remoterise-work/warehaus
cd warehaus
docker compose up -d --build
docker compose --profile seed run --rm ingest seed

---

License

MIT © Dure Sameen

---

Star this repo ⭐ if you found it useful — it really helps.

Built with curiosity in Karachi.