---
title: Welcome to PharmaFlow
description: 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.

**[Getting started](/getting-started)**

Clone the repo, install dependencies, seed the demo data, and run the server and register.

**[Repository overview](/repository-overview)**

Understand the monorepo layout: the server, the register, the offline console, and shared packages.

**[Architecture](/architecture)**

Learn how branches, identity, stock movements, VAT, and sync fit together.

**[API reference](/api)**

Browse every endpoint with schemas, examples, and a Try it playground.

### 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`.

```mermaid
flowchart LR
    subgraph Clients["Clients"]
        Register["apps/register - register UI (Next.js)"]
        Console["apps/console - Tauri shell hosting the register UI"]
    end

    subgraph Server["apps/server - Hono"]
        Auth["auth + RBAC"]
        Sales["sales + returns"]
        Inventory["medicines + batches"]
        Sync["sync push/pull"]
    end

    subgraph Data["Data"]
        Db[("Postgres or SQLite")]
    end

    Register --> Sales
    Register --> Inventory
    Register --> Sync
    Console --> Register
    Console --> Sync
    Sales --> Db
    Inventory --> Db
    Sync --> Db
```

### 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 `###`.