Welcome to PharmaFlow

Everything you need to understand, run, and extend the PharmaFlow monorepo, from the first sale to offline sync and the full API reference.

PharmaFlow is a pharmacy point of sale, inventory, and operations platform. It covers the whole counter workflow: selling medicines with VAT and coupons, tracking batches with FEFO, managing prescriptions and controlled dispensing, running cash sessions, and staying online when the network drops through offline sync.

This knowledgebase is the developer guide to the monorepo. It is written for someone who knows nothing about the project yet and wants to go from zero to shipping a feature, an endpoint, or an operations change.

What PharmaFlow is

PharmaFlow is not just a cash register. It is a counter plus back office plus offline engine. The server owns the hard guarantees once, so every client can focus on the workflow:

• Selling with guarantees - FEFO batch deduction, VAT per policy, coupons, credit limits, idempotent sale creation with invoice numbers.
• Inventory you can trust - batches with expiry, append-only stock movements, transfers, stockcounts, expiry and low stock alerts.
• Safe dispensing - prescriptions with dispense and cancel flows, controlled drug registry, will-call queue, refill reminders.
• Cash discipline - cash sessions with breaks, tender declarations, Z-reports, parked carts, customer credit ledger.
• Offline-first sync - devices register, push queued sales, pull visibility-filtered changes, bootstrap from a snapshot.
• One Hono API, two databases - one Drizzle schema in packages/database, translated between Postgres and SQLite in packages/database/src/schema.ts, with one folder per feature under apps/server/src/features.

A short tour of the sections

• Getting started - prerequisites, install, environment, seed, and running each app.
• Repository overview - how the monorepo is split and why.
• Architecture - the mental model behind branches, auth, stock, VAT, and sync.
• Sales - the sale lifecycle, coupons, returns, parked carts, and sessions.
• Inventory - medicines, batches, purchases, transfers, stockcounts, and alerts.
• Dispensing - prescriptions, controlled drugs, will-call, and refills.
• Operations - customers, suppliers, reports, printing, settings, and compliance.
• Platform - auth, users, branches, audit, sync, and images.
• Guides - practical recipes for common development tasks.
• Tooling - bun, turbo, vitest, and everyday scripts.
• API reference - the generated OpenAPI reference for every endpoint.

Conventions used in this documentation

All code paths are relative to the repository root. Package names follow the @pharmaflow/* scope, for example @pharmaflow/server or @pharmaflow/database. Where a concept lives in code, the documentation points at the exact file so you can open it and read the implementation. All headings inside pages start at ###.