This is a work in progress.

We are currently attempting to build a website to address broken supply chains, such as occur during natural disasters. This is an attempt to build a website that allows makers and manufacturers to match demand for necessary articles which they can make. This matching of demand to supply is a fundamental human problem that could allow lives to be saved and distress relieved during the serial natural disaster that we face.

Our OKH and OKW libraries are implemented as publicly accessible Azure blob containers:

    "Azure_Storage_ServiceName": "https://projdatablobstorage.blob.core.windows.net",
    "Azure_Storage_OKH_ContainerName": "okh",
    "Azure_Storage_OKW_ContainerName": "okw"

These OKHs and OKWs are taken from our repo: https://github.com/helpfulengineering/library.

Helpful created its own OKW template, and added an extenstion to OKH, both of which are defined here: https://github.com/helpfulengineering/OKF-Schema

We are currently working with the Internet of Production Alliance (IoPA) to unify these extensions with their official schemas.

At present, we are using Microsoft Azure to build a basic website.

Harry Pierson has explored an AI-based matching of tools and capabilities that are available to tools and capabilities which are are needed to make needed articles.

The matching engine used for supply-graph flows lives in a separate repository, supply-graph-ai (Open Hardware Manager, OHM): a FastAPI service that this Nuxt app calls from the browser.

We need volunteers. Although we can use a wide variety of skills we need:

1. Programmers who can build a website with Azure
2. Front-end programmers who, using Nuxt/Vue/Boostrap, can implement visual components. Apply here: https://helpful.directory/opportunity?id=Software-Developer---Typescript-446
3. AI programmers who can use vector-matching a LLMs to build a robust matching algorithm.

This repository is a monorepo of separate npm packages (no root package.json). Install and start each part from its package directory.

• Node.js (LTS recommended) and npm
• Azure Functions Core Tools v4 (installed with packages/back-end via npm; ensure func is on your PATH after npm install)
• Azure CLI (az) — install from Microsoft’s docs. You need subscription access and permissions for team resources (blob storage, etc.) as appropriate.
• PostgreSQL — only if you use endpoints that query the database (e.g. /api/incidents). Configure via packages/back-end/.env (see packages/back-end/README.md).
• supply-graph-ai — easiest path is Docker Desktop and docker compose in that repo (service ohm-api maps host port 8001). Alternative: local Python 3.12 / Conda per supply-graph-ai README.

1. Copy local.settings.json.template to local.settings.json in packages/back-end/.

   The Functions host reads Azure storage settings from here. The app fails at startup if Azure_Storage_ServiceName, Azure_Storage_OKH_ContainerName, or Azure_Storage_OKW_ContainerName are missing.

2. If func start reports missing job storage, set AzureWebJobsStorage in local.settings.json to a valid value (for example an Azurite connection string for local development).

3. For database-backed routes, create packages/back-end/.env with PGHOST, PGUSER, PGPASSWORD, PGDATABASE, and optionally PGPORT.

4. From the repo root:

   cd packages/back-end
   npm install
   npm run start

   npm run start runs TypeScript build then func start. HTTP routes are served under /api/... (for example http://localhost:7071/api/listOKHsummaries).

5. az login — use the subscription and permissions your team expects for Azure resources (blob access, etc.).

cd packages/front-end
npm install
npm run dev

Open http://localhost:3000 (and http://localhost:3000/homepage if you use that route).

The front end uses two different configuration mechanisms:

1. nuxt.config.ts → runtimeConfig.public.baseUrl — used by pages that call useRuntimeConfig().public.baseUrl (for example the home page). Default is http://127.0.0.1:7071/api (note 127.0.0.1, not localhost; the project has seen browser/runtime quirks with localhost here).

   Override with BACKEND_URL when starting Nuxt, for example:

   BACKEND_URL=http://127.0.0.1:7071/api npm run dev

2. VITE_* variables — used by supply-graph-related pages (supply-graph-api, product supply tree). Set when starting Nuxt so they match your local Functions host and OHM:

   BACKEND_URL=http://127.0.0.1:7071/api \
   VITE_API_BASE_URL=http://127.0.0.1:7071/api \
   VITE_SUPPLY_GRAPH_AI_URL=http://localhost:8001 \
   npm run dev

   nuxt.config.ts also exposes SUPPLY_GRAPH_AI_URL as runtimeConfig.public.supplyGraphAiUrl for code that reads runtime config; the supply-graph pages above primarily use VITE_SUPPLY_GRAPH_AI_URL.

Clone supply-graph-ai outside this repo (for example next to it: ../supply-graph-ai).

With Docker Desktop running, from the supply-graph-ai repository root:

cd /path/to/supply-graph-ai
cp env.template .env   # if you have not already; edit for storage/API keys as needed
docker compose up ohm-api

The Compose file publishes the FastAPI app on host localhost:8001 (container service ohm-api, port mapping 8001:8001). Confirm it is up:

• http://localhost:8001/health
• http://localhost:8001/docs

You can use docker compose up instead of docker compose up ohm-api if you intend to start the full stack defined in that repo’s docker-compose.yml.

For active development inside supply-graph-ai with hot reload:

cd /path/to/supply-graph-ai
conda create -n supply-graph-ai python=3.12
conda activate supply-graph-ai
pip install -r requirements.txt
pip install -e .
cp env.template .env
python run.py

Same default URL: http://localhost:8001 (API_PORT in that project’s settings).

Match endpoint: POST {VITE_SUPPLY_GRAPH_AI_URL}/v1/api/match — this is the route the Open Hardware Manager exposes; it is not the same as the stub in packages/mock-api (POST /v1/match).

End-to-end match testing: Follow docs/match-endpoint-integration.md for the ordered verification steps (OHM health, blob URL reachability from Docker, Azure Functions, CORS, and curl). Shared client helpers live in packages/front-end/utils/ohmMatch.ts. To assert the same JSON body and headers as the UI against a running OHM, run OKH_FNAME=… node scripts/verify-ohm-match.mjs from the repo root (see doc §6).

CORS: In development, supply-graph-ai typically allows browser calls; if you change origins or run production-like settings, set CORS_ORIGINS in OHM’s environment so http://localhost:3000 (and/or http://127.0.0.1:3000) is allowed.

Ports: Do not run packages/mock-api on port 8001 at the same time as OHM; they conflict. Use the mock only when you want a minimal stub instead of the real Python service.

A minimal Express server for quick stubs. The code listens on port 8001 and implements POST /v1/match, which is not the same path as OHM’s POST /v1/api/match. Use it only when you are not running supply-graph-ai on 8001.

cd packages/mock-api
npm install
npm run dev

The older prototype website is implemented with Github Pages.

TypeScript port of original Project Data Python Code.