# PharmaFlow Knowledgebase

> The complete developer documentation for PharmaFlow, a pharmacy point of sale, inventory, and offline-first operations platform built on Hono, Next.js, and Postgres.

## Docs

- [Welcome to PharmaFlow](https://pharmaflow-rho.vercel.app/): Everything you need to understand, run, and extend the PharmaFlow monorepo, from the first sale to offline sync and the full API reference.
- [Getting started](https://pharmaflow-rho.vercel.app/getting-started): Set up PharmaFlow on your machine, prerequisites, install, environment configuration, demo seed, and running the apps.
- [Repository overview](https://pharmaflow-rho.vercel.app/repository-overview): How the PharmaFlow monorepo is split across server features, client apps, and shared packages, and why.

## Architecture

- [Architecture](https://pharmaflow-rho.vercel.app/architecture): The mental model behind PharmaFlow, branches, auth, stock movements, VAT, and offline sync.
- [Request Lifecycle](https://pharmaflow-rho.vercel.app/architecture/request-lifecycle): Follow one HTTP request through middleware, auth, handlers, and errors so you can trace any endpoint.
- [Branches and Scoping](https://pharmaflow-rho.vercel.app/architecture/branches-and-scoping): Learn how branch isolation keeps stock and sales apart, and where admins cross the line.
- [Stock and FEFO](https://pharmaflow-rho.vercel.app/architecture/stock-and-fefo): Understand batches, the append-only movement ledger, and how each sale drains the earliest expiry first.
- [VAT and Money](https://pharmaflow-rho.vercel.app/architecture/vat-and-money): See how the org tax policy prices every line, applies coupons, and stores money safely.
- [Offline Sync](https://pharmaflow-rho.vercel.app/architecture/offline-sync): Learn how devices register, queue sales locally, replay them safely, and pull only the changes they may see.

## Sales

- [Sales](https://pharmaflow-rho.vercel.app/sales): The sale lifecycle, coupons, returns with credit notes, cash sessions, and parked carts.
- [Selling at the Counter](https://pharmaflow-rho.vercel.app/sales/selling-at-the-counter): Post idempotent sales with items, split payments, coupons, VAT, and FEFO deduction.
- [Coupons and Discounts](https://pharmaflow-rho.vercel.app/sales/coupons-and-discounts): Validate coupon codes at the register and manage them as an admin or branch manager.
- [Returns and Credit Notes](https://pharmaflow-rho.vercel.app/sales/returns-and-credit-notes): Look up invoices by number, post partial returns with restocking, and issue credit notes.
- [Sessions and Parked Sales](https://pharmaflow-rho.vercel.app/sales/sessions-and-parked): Open cash sessions, take breaks, declare tender, close with a Z-report, and park carts.

## Inventory

- [Inventory](https://pharmaflow-rho.vercel.app/inventory): Medicines, batches, purchasing, transfers, stockcounts, and expiry handling.
- [Medicines and Batches](https://pharmaflow-rho.vercel.app/inventory/medicines-and-batches): Search medicines with per-branch stock, manage the medicine record, read movements, and query the controlled registry.
- [Purchasing and Purchase Orders](https://pharmaflow-rho.vercel.app/inventory/purchasing-and-purchase-orders): Receive batches directly, run the draft to received purchase order flow, and read the stock movement ledger.
- [Transfers and Stockcount](https://pharmaflow-rho.vercel.app/inventory/transfers-and-stockcount): Move stock between branches with FEFO deduction and reconcile shelf counts with system quantities.
- [Alerts and Expiry](https://pharmaflow-rho.vercel.app/inventory/alerts-and-expiry): Query low-stock, expiring, and expired batches and act on them before they cost you a sale or a write-off.

## Dispensing

- [Dispensing](https://pharmaflow-rho.vercel.app/dispensing): Prescriptions, the controlled drug registry, will-call pickup, and refill reminders.
- [Prescriptions](https://pharmaflow-rho.vercel.app/dispensing/prescriptions): Create, list, dispense, and cancel branch prescriptions in PharmaFlow.
- [Controlled drugs](https://pharmaflow-rho.vercel.app/dispensing/controlled-drugs): Flag controlled medicines, read the dispense log, and keep statutory registers inspection ready.
- [Will-call and refills](https://pharmaflow-rho.vercel.app/dispensing/will-call-and-refills): Queue finished orders for pickup, search generics, and schedule refill reminders.

## Operations

- [Operations](https://pharmaflow-rho.vercel.app/operations): Customers and credit, suppliers and finance, reports, printing, settings, and compliance.
- [Customers and credit](https://pharmaflow-rho.vercel.app/operations/customers-and-credit): Search customers, manage credit limits, read the ledger, and record payments that reduce the balance.
- [Suppliers and finance](https://pharmaflow-rho.vercel.app/operations/suppliers-and-finance): Manage supplier records, track supplier invoices and payments, quarantine batches, and get reorder suggestions.
- [Reports and dashboard](https://pharmaflow-rho.vercel.app/operations/reports-and-dashboard): Read the dashboard summary and branch comparison, then run inventory, purchases, sales, pharmacist, and VAT reports.
- [Printing and settings](https://pharmaflow-rho.vercel.app/operations/printing-and-settings): Register branch printers, design receipt templates, audit print jobs, and configure the org settings singleton.
- [Compliance](https://pharmaflow-rho.vercel.app/operations/compliance): Pull the prescription and classified-drugs books, preview the fiscal payload, and list registered devices.

## Platform

- [Platform](https://pharmaflow-rho.vercel.app/platform): Authentication, users, branches, the audit log, the sync protocol, and image uploads.
- [Authentication and Users](https://pharmaflow-rho.vercel.app/platform/authentication-and-users): Log in, understand the HS256 JWT claims, enforce role checks, and manage users through the admin endpoints.
- [Branches](https://pharmaflow-rho.vercel.app/platform/branches): Create branches with unique codes, list them with active filters, and understand how branch scoping isolates data.
- [Audit Log](https://pharmaflow-rho.vercel.app/platform/audit-log): Query the append-only audit trail by entity, action, branch, user, search text, and date window.
- [Sync Protocol](https://pharmaflow-rho.vercel.app/platform/sync-protocol): Register devices, push idempotent offline sales, pull visibility-filtered deltas, and bootstrap with snapshots.
- [Images and Branding](https://pharmaflow-rho.vercel.app/platform/images-and-branding): Upload medicine photos and the org logo through presigned S3 URLs with type and size validation.

## Guides

- [Guides](https://pharmaflow-rho.vercel.app/guides): Step-by-step recipes for running, extending, and operating PharmaFlow.
- [Running the Platform](https://pharmaflow-rho.vercel.app/guides/running-the-platform): Install prerequisites, configure env, seed the demo, boot server plus register plus docs, and verify with health and login.
- [Adding an Endpoint](https://pharmaflow-rho.vercel.app/guides/adding-an-endpoint): Add a feature route with auth, role checks, zod validation, audit logging, sync emission, mounting, OpenAPI, and tests.
- [Selling End to End](https://pharmaflow-rho.vercel.app/guides/selling-end-to-end): Open a session, park a cart, post an idempotent sale with DEMO10, tender cash, close out, and return part of it.
- [Offline-First Flow](https://pharmaflow-rho.vercel.app/guides/offline-first-flow): Register a device, snapshot it, queue sales offline, push the replay, pull deltas, and handle conflicts.

## Tooling

- [Tooling](https://pharmaflow-rho.vercel.app/tooling): The bun, turbo, and vitest workflow behind everyday PharmaFlow development.
- [Bun and turbo](https://pharmaflow-rho.vercel.app/tooling/bun-and-turbo): Run the PharmaFlow monorepo with bun workspaces and turbo tasks.
- [Testing](https://pharmaflow-rho.vercel.app/tooling/testing): Run vitest suites, bypass login rate limits in tests, and reset demo data.

## API

- [PharmaFlow API](https://pharmaflow-rho.vercel.app/api)

### Alerts

- [List expired batches](https://pharmaflow-rho.vercel.app/api/alerts/list-expired-alerts)
- [List expiring batches](https://pharmaflow-rho.vercel.app/api/alerts/list-expiry-alerts)
- [List low stock alerts](https://pharmaflow-rho.vercel.app/api/alerts/list-low-stock-alerts)

### Audit

- [List audit entries](https://pharmaflow-rho.vercel.app/api/audit/list-audit-entries)
- [Read an audit entry](https://pharmaflow-rho.vercel.app/api/audit/get-audit-entry)

### Auth

- [Change the caller's password](https://pharmaflow-rho.vercel.app/api/auth/change-password)
- [Log in and issue an access token](https://pharmaflow-rho.vercel.app/api/auth/login-user)
- [Read the signed in user](https://pharmaflow-rho.vercel.app/api/auth/get-current-user)

### Branches

- [Create a branch](https://pharmaflow-rho.vercel.app/api/branches/create-branch)
- [List branches](https://pharmaflow-rho.vercel.app/api/branches/list-branches)
- [Read a branch](https://pharmaflow-rho.vercel.app/api/branches/get-branch)
- [Update a branch](https://pharmaflow-rho.vercel.app/api/branches/update-branch)

### Categories

- [Create a category](https://pharmaflow-rho.vercel.app/api/categories/create-category)
- [Delete a category](https://pharmaflow-rho.vercel.app/api/categories/delete-category)
- [List the category catalogue](https://pharmaflow-rho.vercel.app/api/categories/list-categories)
- [Update a category](https://pharmaflow-rho.vercel.app/api/categories/update-category)

### Compliance

- [List registered devices](https://pharmaflow-rho.vercel.app/api/compliance/list-devices)
- [List the classified drugs book](https://pharmaflow-rho.vercel.app/api/compliance/list-classified-drugs-book)
- [List the prescription book](https://pharmaflow-rho.vercel.app/api/compliance/list-prescription-book)
- [Preview the EFRIS payload for a sale](https://pharmaflow-rho.vercel.app/api/compliance/get-efris-preview)
- [Restore a revoked device](https://pharmaflow-rho.vercel.app/api/compliance/restore-device)
- [Revoke a device](https://pharmaflow-rho.vercel.app/api/compliance/revoke-device)

### Coupons

- [Create a coupon](https://pharmaflow-rho.vercel.app/api/coupons/create-coupon)
- [List coupons](https://pharmaflow-rho.vercel.app/api/coupons/list-coupons)
- [Update a coupon](https://pharmaflow-rho.vercel.app/api/coupons/update-coupon)
- [Validate a coupon code](https://pharmaflow-rho.vercel.app/api/coupons/validate-coupon)

### Currency

- [Check a sale rate against tolerance](https://pharmaflow-rho.vercel.app/api/currency/check-exchange-rate-tolerance)
- [Create a currency](https://pharmaflow-rho.vercel.app/api/currency/create-currency)
- [File an exchange rate](https://pharmaflow-rho.vercel.app/api/currency/create-exchange-rate)
- [List exchange rates](https://pharmaflow-rho.vercel.app/api/currency/list-exchange-rates)
- [List the currency registry](https://pharmaflow-rho.vercel.app/api/currency/list-currencies)
- [Read the caller's branch currency](https://pharmaflow-rho.vercel.app/api/currency/get-branch-currency)
- [Read the currency overview](https://pharmaflow-rho.vercel.app/api/currency/get-currency-overview)
- [Resolve the effective rate](https://pharmaflow-rho.vercel.app/api/currency/get-effective-rate)
- [Update a currency](https://pharmaflow-rho.vercel.app/api/currency/update-currency)

### Customers

- [Create a customer](https://pharmaflow-rho.vercel.app/api/customers/create-customer)
- [Get a customer](https://pharmaflow-rho.vercel.app/api/customers/get-customer)
- [Get a customer ledger](https://pharmaflow-rho.vercel.app/api/customers/get-customer-ledger)
- [List customers](https://pharmaflow-rho.vercel.app/api/customers/list-customers)
- [Record a customer payment](https://pharmaflow-rho.vercel.app/api/customers/create-customer-payment)
- [Update a customer](https://pharmaflow-rho.vercel.app/api/customers/update-customer)

### Dashboard

- [Compare branch revenue](https://pharmaflow-rho.vercel.app/api/dashboard/get-branch-comparison)
- [Read the dashboard summary](https://pharmaflow-rho.vercel.app/api/dashboard/get-dashboard-summary)

### Dispensing

- [Add a will-call pickup](https://pharmaflow-rho.vercel.app/api/dispensing/create-will-call)
- [Collect a will-call pickup](https://pharmaflow-rho.vercel.app/api/dispensing/pickup-will-call)
- [Create a refill reminder](https://pharmaflow-rho.vercel.app/api/dispensing/create-refill-reminder)
- [List pending refill reminders](https://pharmaflow-rho.vercel.app/api/dispensing/list-refill-reminders)
- [List the will-call queue](https://pharmaflow-rho.vercel.app/api/dispensing/list-will-call)
- [Search medicines by generic name](https://pharmaflow-rho.vercel.app/api/dispensing/search-generic-medicines)

### Health

- [Check service and database health](https://pharmaflow-rho.vercel.app/api/health/get-health)

### Images

- [Attach an uploaded photo to a medicine](https://pharmaflow-rho.vercel.app/api/images/set-medicine-image)
- [Create a branding logo upload URL](https://pharmaflow-rho.vercel.app/api/images/create-branding-upload-url)
- [Create a medicine photo upload URL](https://pharmaflow-rho.vercel.app/api/images/create-medicine-upload-url)
- [Set the organisation logo](https://pharmaflow-rho.vercel.app/api/images/set-brand-logo)

### Marketing

- [Record a marketing enquiry](https://pharmaflow-rho.vercel.app/api/marketing/create-marketing-contact)

### Medicines

- [Create a medicine](https://pharmaflow-rho.vercel.app/api/medicines/create-medicine)
- [Deactivate a medicine](https://pharmaflow-rho.vercel.app/api/medicines/delete-medicine)
- [List a medicine's stock movements](https://pharmaflow-rho.vercel.app/api/medicines/get-medicine-movements)
- [List the controlled dispensing registry](https://pharmaflow-rho.vercel.app/api/medicines/get-controlled-registry)
- [List the medicine catalogue](https://pharmaflow-rho.vercel.app/api/medicines/list-medicines)
- [Read a medicine](https://pharmaflow-rho.vercel.app/api/medicines/get-medicine)
- [Update a medicine](https://pharmaflow-rho.vercel.app/api/medicines/update-medicine)

### Ops

- [Approve or reject an approval](https://pharmaflow-rho.vercel.app/api/ops/decide-approval)
- [List manager approvals](https://pharmaflow-rho.vercel.app/api/ops/list-approvals)
- [List the published changelog](https://pharmaflow-rho.vercel.app/api/ops/list-changelog)
- [Publish a changelog entry](https://pharmaflow-rho.vercel.app/api/ops/create-changelog)
- [Request a manager approval](https://pharmaflow-rho.vercel.app/api/ops/create-approval)

### Parked

- [List parked carts](https://pharmaflow-rho.vercel.app/api/parked/list-parked)
- [Park a cart](https://pharmaflow-rho.vercel.app/api/parked/park-cart)
- [Recall a parked cart](https://pharmaflow-rho.vercel.app/api/parked/recall-parked)
- [Void a parked cart](https://pharmaflow-rho.vercel.app/api/parked/void-parked)

### Prescriptions

- [Cancel a prescription](https://pharmaflow-rho.vercel.app/api/prescriptions/cancel-prescription)
- [Create a prescription](https://pharmaflow-rho.vercel.app/api/prescriptions/create-prescription)
- [Dispense a prescription](https://pharmaflow-rho.vercel.app/api/prescriptions/dispense-prescription)
- [Get a prescription](https://pharmaflow-rho.vercel.app/api/prescriptions/get-prescription)
- [List prescriptions](https://pharmaflow-rho.vercel.app/api/prescriptions/list-prescriptions)

### Printing

- [Create a receipt template](https://pharmaflow-rho.vercel.app/api/printing/create-receipt-template)
- [List print jobs](https://pharmaflow-rho.vercel.app/api/printing/list-print-jobs)
- [List printers](https://pharmaflow-rho.vercel.app/api/printing/list-printers)
- [List receipt templates](https://pharmaflow-rho.vercel.app/api/printing/list-receipt-templates)
- [Record a print job](https://pharmaflow-rho.vercel.app/api/printing/create-print-job)
- [Register a printer](https://pharmaflow-rho.vercel.app/api/printing/create-printer)
- [Remove a printer](https://pharmaflow-rho.vercel.app/api/printing/delete-printer)
- [Update a printer](https://pharmaflow-rho.vercel.app/api/printing/update-printer)

### PurchaseOrders

- [Create a purchase order](https://pharmaflow-rho.vercel.app/api/purchaseorders/create-purchase-order)
- [List purchase orders](https://pharmaflow-rho.vercel.app/api/purchaseorders/list-purchase-orders)
- [List suggested reorders](https://pharmaflow-rho.vercel.app/api/purchaseorders/list-suggested-purchase-orders)
- [Read a purchase order](https://pharmaflow-rho.vercel.app/api/purchaseorders/get-purchase-order)
- [Receive a purchase order](https://pharmaflow-rho.vercel.app/api/purchaseorders/receive-purchase-order)
- [Send or cancel a purchase order](https://pharmaflow-rho.vercel.app/api/purchaseorders/update-purchase-order-status)

### Purchases

- [List expiring batches](https://pharmaflow-rho.vercel.app/api/purchases/list-expiring-purchases)
- [List received batches](https://pharmaflow-rho.vercel.app/api/purchases/list-purchases)
- [List stock movements](https://pharmaflow-rho.vercel.app/api/purchases/list-purchase-movements)
- [Read a received batch](https://pharmaflow-rho.vercel.app/api/purchases/get-purchase)
- [Receive a batch](https://pharmaflow-rho.vercel.app/api/purchases/create-purchase)
- [Write off a batch](https://pharmaflow-rho.vercel.app/api/purchases/write-off-purchase)

### Reports

- [Report on purchase spend](https://pharmaflow-rho.vercel.app/api/reports/get-purchases-report)
- [Report on sales](https://pharmaflow-rho.vercel.app/api/reports/get-sales-report)
- [Report on the medicine inventory](https://pharmaflow-rho.vercel.app/api/reports/get-inventory-report)
- [Report on VAT by month](https://pharmaflow-rho.vercel.app/api/reports/get-vat-report)
- [Report sales by pharmacist](https://pharmaflow-rho.vercel.app/api/reports/get-pharmacist-sales-report)

### Returns

- [Create a return](https://pharmaflow-rho.vercel.app/api/returns/create-return)
- [List returns](https://pharmaflow-rho.vercel.app/api/returns/list-returns)
- [Look up a returnable invoice](https://pharmaflow-rho.vercel.app/api/returns/get-return-lookup)
- [Read a return](https://pharmaflow-rho.vercel.app/api/returns/get-return)

### Sales

- [Create a sale](https://pharmaflow-rho.vercel.app/api/sales/create-sale)
- [List sales](https://pharmaflow-rho.vercel.app/api/sales/list-sales)
- [Read a sale](https://pharmaflow-rho.vercel.app/api/sales/get-sale)
- [Read a sale invoice identity](https://pharmaflow-rho.vercel.app/api/sales/get-sale-invoice)

### Sessions

- [Close the caller's cash session](https://pharmaflow-rho.vercel.app/api/sessions/close-session)
- [Declare the counted cash](https://pharmaflow-rho.vercel.app/api/sessions/declare-tender)
- [End the caller's open break](https://pharmaflow-rho.vercel.app/api/sessions/end-break)
- [List closed cash sessions](https://pharmaflow-rho.vercel.app/api/sessions/list-session-history)
- [List the caller's tender declarations](https://pharmaflow-rho.vercel.app/api/sessions/list-tender-history)
- [List the sales in a session](https://pharmaflow-rho.vercel.app/api/sessions/get-session-sales)
- [Open a cash session](https://pharmaflow-rho.vercel.app/api/sessions/open-session)
- [Read a session Z-report](https://pharmaflow-rho.vercel.app/api/sessions/get-z-report)
- [Read the caller's open session](https://pharmaflow-rho.vercel.app/api/sessions/get-current-session)
- [Start a break on the open session](https://pharmaflow-rho.vercel.app/api/sessions/start-break)

### Settings

- [Read the organisation settings](https://pharmaflow-rho.vercel.app/api/settings/get-settings)
- [Update the organisation settings](https://pharmaflow-rho.vercel.app/api/settings/update-settings)

### Stockcount

- [Read the branch stock count sheet](https://pharmaflow-rho.vercel.app/api/stockcount/get-stock-count-sheet)
- [Submit a stock count](https://pharmaflow-rho.vercel.app/api/stockcount/submit-stock-count)

### SupplierFinance

- [List reorder suggestions](https://pharmaflow-rho.vercel.app/api/supplierfinance/list-reorder-suggestions)
- [List supplier invoices](https://pharmaflow-rho.vercel.app/api/supplierfinance/list-supplier-invoices)
- [Quarantine or release a batch](https://pharmaflow-rho.vercel.app/api/supplierfinance/set-batch-quarantine)
- [Record a payment on an invoice](https://pharmaflow-rho.vercel.app/api/supplierfinance/record-supplier-invoice-payment)
- [Record a supplier invoice](https://pharmaflow-rho.vercel.app/api/supplierfinance/create-supplier-invoice)

### Suppliers

- [Create a supplier](https://pharmaflow-rho.vercel.app/api/suppliers/create-supplier)
- [Deactivate a supplier](https://pharmaflow-rho.vercel.app/api/suppliers/delete-supplier)
- [List suppliers](https://pharmaflow-rho.vercel.app/api/suppliers/list-suppliers)
- [Read a supplier](https://pharmaflow-rho.vercel.app/api/suppliers/get-supplier)
- [Update a supplier](https://pharmaflow-rho.vercel.app/api/suppliers/update-supplier)

### Sync

- [List pending sync conflicts](https://pharmaflow-rho.vercel.app/api/sync/list-sync-conflicts)
- [Pull changes since a revision](https://pharmaflow-rho.vercel.app/api/sync/pull-sync-changes)
- [Push queued changes](https://pharmaflow-rho.vercel.app/api/sync/push-sync-changes)
- [Register a till](https://pharmaflow-rho.vercel.app/api/sync/register-sync-device)
- [Resolve a sync conflict](https://pharmaflow-rho.vercel.app/api/sync/resolve-sync-conflict)
- [Snapshot the catalogue](https://pharmaflow-rho.vercel.app/api/sync/get-sync-snapshot)

### Transfers

- [Create a batch stock transfer](https://pharmaflow-rho.vercel.app/api/transfers/create-batch-transfer)
- [Create a stock transfer](https://pharmaflow-rho.vercel.app/api/transfers/create-transfer)
- [List stock transfers](https://pharmaflow-rho.vercel.app/api/transfers/list-transfers)

### Users

- [Create a user](https://pharmaflow-rho.vercel.app/api/users/create-user)
- [List users](https://pharmaflow-rho.vercel.app/api/users/list-users)
- [Read a user](https://pharmaflow-rho.vercel.app/api/users/get-user)
- [Reset a user's password](https://pharmaflow-rho.vercel.app/api/users/reset-user-password)
- [Update a user](https://pharmaflow-rho.vercel.app/api/users/update-user)

## Agent resources

- [llms-full.txt](https://pharmaflow-rho.vercel.app/llms-full.txt): The full Markdown of every page in one file.
- [Page Markdown](https://pharmaflow-rho.vercel.app/index.md): Append `.md` to any page URL to fetch that page as raw Markdown.
- [JSON API](https://pharmaflow-rho.vercel.app/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://pharmaflow-rho.vercel.app/openapi.json.
- [API catalog](https://pharmaflow-rho.vercel.app/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here.
- [AI catalog](https://pharmaflow-rho.vercel.app/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs).
- [agent-readability.json](https://pharmaflow-rho.vercel.app/agent-readability.json): Manifest of every agent-facing artifact on this site.
- [Sitemap](https://pharmaflow-rho.vercel.app/sitemap.xml): Every indexable page URL with its last-modified date.