lishebora.aphrc.org

Documentation

Admin API Endpoints

Current backend endpoints used by the LisheBora web admin console. These endpoints are read-only today and should be protected by admin authentication before broader team access.

Public web — product search KNPM display

The home-page product search shows Kenya Nutrient Profile Model (KNPM) results using octagon icons for warnings (same assets as the mobile app). Fit-for-consumption uses a green checkmark on web. An earlier layout crammed a text badge, a four-column nutrition grid, and long threshold explanations into one card — it read poorly on narrow screens and duplicated what the octagons already communicate.

Avoid on web search results

  • Text-only pills such as “Black octagon warning” instead of icons
  • Inline Sugar / Fat / Sat. fat / Sodium grids beside the label
  • Long joined reasons paragraphs in the result card

Current web pattern

  • Centered octagon SVGs with breathing room (from knpm_label.octagons)
  • Fit-for-consumption products use the green checkmark icon (not the white mobile asset)
  • Up to three “Better swaps” from /products/search/recommendations
High in sugar
High in sugar
High in fat
High in fat
High in salt
High in salt
Fit for consumption
Fit for consumption

Implementation: app/_components/product-search-result.tsx and lib/knpm-ui.ts. Static assets live in public/images/octagons/.

Dashboard Reads

GET

/api/v1/admin/summary

Operational totals for users, scans, uploads, products, barcode mappings, and missing barcodes.

GET

/api/v1/admin/users?limit=50

Registered users, BMI/profile fields, scan counts, and last scan date.

GET

/api/v1/admin/scans?limit=50

OCR and barcode scan events with product name, KNPM label, nutrients, image URL, and date.

GET

/api/v1/admin/products?limit=200

Reference nutrition catalogue, category/form fields, nullable price fields, nutrients, and quality flags.

GET

/api/v1/admin/barcodes?limit=200

Resolved barcode mappings plus unresolved missing barcode rows.

GET

/api/v1/admin/uploads?limit=50

Saved scan images, OCR source, product name, success state, user label, and created date.

GET

/api/v1/admin/exports

List of admin export and analytics endpoints shown in the Exports page.

Analytics

GET

/api/v1/admin/analytics/health-summary?limit=25

Anonymized KNPM label distribution, scan type/source counts, and top products with nutrient averages.

GET

/api/v1/admin/analytics/nutrients?limit=10

Observed nutrient counts, averages, max values, and highest sugar/fat/sodium product rows.

CSV Exports

GET

/api/v1/admin/exports/scans.csv?limit=5000

Anonymized scan export with product, source, KNPM label, nutrients, image URL, error, and date.

GET

/api/v1/admin/exports/uploads.csv?limit=5000

Anonymized image-backed scan export for image review teams.

GET

/api/v1/admin/exports/products.csv?limit=10000

Reference products with nutrition, category, package, quality, and nullable price fields.

GET

/api/v1/admin/missing-products/export?format=csv

Pending barcode/product misses for supervisor review and product enrichment.

Review Utilities

GET

/api/v1/admin/missing-products?limit=1000

Missing barcode/product rows with search count, first seen, last seen, and notes.

STATIC

/api/v1/uploads/scan_images/...

Serves saved scan images referenced by admin scans/uploads. Use only in authenticated admin review flows.

Product Price Fields

Prices are additive and nullable on reference products only. They do not change mobile scan responses.

price_amountprice_currencyprice_rawprice_source

Production Backfill

After deploying the backend image that contains the script, run this once to populate reference product prices from the bundled source CSV.

docker compose -f docker-compose.prod.yml --env-file .env.prod exec backend python scripts/backfill_reference_prices.py