GitHub - siddharth7113/PharmaFlow: IIT Madras Project for Software Engineering.

PharmaFlow - Frontend Overview & Local Setup

What is PharmaFlow?

PharmaFlow is an intelligent pharmacy operations platform built for retail pharmacies. It aims to digitize and streamline day-to-day pharmacy workflows, including:

Zero-entry invoice scanning - point the camera at a distributor's bill or upload a PDF; Google Cloud Vision + a format-agnostic parser extract line items into a review-ready draft receipt. Manual entry still available as a first-class fallback.
Inventory management - per-product view with batch-level detail, server-side filters for low-stock / near-expiry / out-of-stock, and FEFO allocation on sales.
Expiry management - near-expiry batches surface on the dashboard, inventory list, and returns flow.
Sales & invoice generation - create customer invoices with line items drawn FEFO from inventory batches; print via a self-contained popup window. Business-profile completeness is enforced before an invoice can be generated (invoices need a legally-compliant header).
Past Invoices with an OWNER-only Staff audit column - who rang each sale survives even if the employee is removed from the team.
Returns to distributor - select batches, auto-reserve the stock, print a regulation-compliant debit note (with the pharmacy's GSTIN, drug licence, and bank details), and record pickup to post an expense credit.
Expense tracking - log manual expenses; return credits surface automatically as negative-amount rows.
Analytics (owner-only) - one-page snapshot of revenue, cost-of-goods (from FEFO allocations), gross/net profit, sales trend, top products, payment-mode split, expense breakdown, and an inventory-health tile. Period selector toggles 7/30/90/365-day rolling windows.
Settings & Profile - business profile, bank details, distributor list (real API-backed CRUD; renames cascade to history via FK), profile-picture upload, self-service password change.
Team management (owner-only /team page) - invite / promote / disable / soft-remove MANAGER + STAFF accounts with server-generated temp passwords returned once in a copy-banner. Re-inviting a removed email reactivates the original row so every audit trail remains consistent.
Role-based access control - OWNER / MANAGER / STAFF enforced in two layers: <RoleRoute> wrappers in the frontend routes + @role_required() decorators on every mutating backend endpoint.

Developer docs

backend/docs/settings-architecture.md - start here for the Settings page, RBAC matrix, team management, distributors, profile picture upload, password rotation. Ties together every subsystem added with the April 2026 settings work.
backend/docs/inventory-architecture.md - end-to-end walkthrough of the inventory / receipts / returns / OCR subsystems.
backend/docs/invoices-architecture.md - sales-invoice + FEFO allocation logic (including the completeness gate + creator audit fields).
backend/docs/analytics-architecture.md - OWNER-only reporting page: KPI formulas (revenue, COGS, gross/net profit), period resolution, inventory-health buckets, and the multi-tenant scoping tests.
backend/docs/dashboard-architecture.md - role-aware landing page: per-role widget matrix, pending-queue semantics (receipts/returns/expenses), and the rationale for STAFF seeing only their own sales.
backend/docs/auth-architecture.md - authentication primitives + business membership model.
backend/docs/api-spec.yaml - OpenAPI 3 spec for every live endpoint. Drop it into Swagger UI / Redoc to browse interactively.

Frontend Directory Structure

frontend/
├── index.html              # App shell, loads /src/main.jsx
├── package.json            # Dependencies & scripts (named: pharmaflow-frontend)
├── vite.config.js          # Vite config - dev server on :5173, proxies /api to :5000
├── .gitignore
└── src/
    ├── main.jsx            # React entry point - wraps app in BrowserRouter + Toaster
    ├── App.jsx             # Root - applies ThemeProvider + AuthProvider
    ├── routes/
    │   └── AppRoutes.jsx   # All routes with <RoleRoute allowed=[...]> per-page gating
    ├── pages/
    │   ├── public/         # LandingPage, AboutUsPage, ContactUsPage
    │   ├── auth/           # LoginPage (also handles /signup)
    │   ├── dashboard/      # DashboardPage (with setup + temp-password banners)
    │   ├── inventory/      # InventoryListPage, InventoryDetailPage
    │   ├── sales/          # InvoiceGeneratorPage, PastInvoicesPage (OWNER/MANAGER)
    │   ├── receipts/       # DrugReceiptsPage, ScanReceiptPage, ReviewReceiptPage, ManualReceiptPage (OWNER/MANAGER)
    │   ├── returns/        # ReturnsManagementPage, ReturnReceiptPage (OWNER/MANAGER)
    │   ├── expenses/       # ExpensesPage (OWNER)
    │   ├── analytics/      # AnalyticsPage (OWNER)
    │   ├── team/           # TeamPage - invite/promote/remove staff (OWNER)
    │   └── settings/       # SettingsPage - profile, password, business, bank, distributors
    ├── layouts/            # PublicLayout, DashboardLayout, AuthLayout
    ├── context/            # AuthContext, ThemeContext
    ├── components/         # Reusable UI components (incl. settings/, expenses/, common/)
    ├── services/           # api.js axios client + per-domain services
    │                       #   businessService, distributorService, teamService,
    │                       #   invoiceService, receiptService, returnService,
    │                       #   expenseService, inventoryService, analyticsService,
    │                       #   dashboardService
    ├── data/               # Static seed data for dashboard placeholders
    └── styles/
        ├── index.css       # Global styles + .sr-only utility
        └── variables.css   # CSS custom properties (light + dark themes)

Key Architectural Details

Concern	Detail
Framework	React 18 with JSX
Build Tool	Vite 5
Routing	React Router DOM v6
API Calls	Axios (proxied via Vite to backend at `http://localhost:5000`)
Animations	Framer Motion
Charts	Recharts
Notifications	react-hot-toast
Icons	Lucide React
Fuzzy Search	Fuse.js
File Upload	react-dropzone
Date Utils	date-fns
Path Alias	`@` maps to `./src`

Auth & Route Guards

ProtectedRoute - redirects unauthenticated users to /login.
RoleRoute allowed={[…]} - centralised role gate used by every role-scoped page in AppRoutes.jsx (e.g. <RoleRoute allowed={['OWNER','MANAGER']}>). See the full matrix in backend/docs/settings-architecture.md.
Auth state is managed globally via AuthContext; updateUser() is defensive about partial updates so a stray role: null can't silently demote a user.

Running the Frontend Locally

Prerequisites

Node.js ≥ 18 (recommended)
npm

Steps

# 1. Clone the repository and switch to the correct branch
git clone https://github.com/siddharth7113/SE_project.git
cd SE_project

# 2. Navigate into the frontend directory
cd frontend

# 3. Copy the environment file and fill in your Google Client ID
cp .env.example .env
# Then open .env and set: VITE_GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com

# 4. Install dependencies
npm install

# 5. Start the development server
npm run dev

The app will be available at http://localhost:5173.

Available Scripts

Command	Description
`npm run dev`	Start Vite dev server on port 5173
`npm run build`	Build for production (outputs to `dist/`)
`npm run preview`	Preview the production build locally
`npm run lint`	Run ESLint across all `.js` and `.jsx` files

API Documentation

The full REST API specification is defined in OpenAPI 3.0 (Swagger) format:

📄 backend/docs/api-spec.yaml

You can preview it by pasting the contents into Swagger Editor, or install the VS Code OpenAPI extension for inline preview.

Backend - Flask + PostgreSQL

The backend lives in backend/ and uses Flask, SQLAlchemy ORM, and PostgreSQL 16.

Backend Prerequisites

Python ≥ 3.11
uv (Python package manager) - install with curl -LsSf https://astral.sh/uv/install.sh | sh
Docker & Docker Compose (for PostgreSQL)

Backend Setup for Windows

# 1. Start PostgreSQL (creates both dev and test databases automatically)
cd backend
.\check-docker.ps1
docker compose up -d

# 2. Configure Environment Variables
# Copy the example env file. You MUST configure JWT_SECRET_KEY and GOOGLE_CLIENT_ID 
# for full authentication functionality.
copy .env.example .env
notepad .env  # Or use your preferred editor like VS Code: code .env

# 3. Create virtual environment & install dependencies
python -m venv .venv
.\.venv\Scripts\activate
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

# 4. Run database migrations
$env:FLASK_APP="manage.py"
.\.venv\Scripts\python.exe -m flask db upgrade

# 5. Seed the database with sample data
.\.venv\Scripts\python.exe seed.py

# 6. Start the development server
.\.venv\Scripts\python.exe run.py

Backend Setup for Linux

# 1. Start PostgreSQL (creates both dev and test databases automatically)
cd backend
docker compose up -d

# 2. Configure Environment Variables
# Copy the example env file. You MUST configure JWT_SECRET_KEY and GOOGLE_CLIENT_ID 
# for full authentication functionality.
cp .env.example .env
nano .env

# 3. Create virtual environment & install dependencies
uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt

# 4. Run database migrations
FLASK_APP=manage.py flask db upgrade

# 5. Seed the database with sample data
python seed.py

# 6. Start the development server
python run.py

The backend server will be available at http://localhost:5000.

Running Tests for Linux

cd backend
source .venv/bin/activate
python -m pytest tests/ -v

Running Tests for Windows

cd backend
.\.venv\Scripts\python.exe -m pytest tests -v

All 250 tests should pass (including 39 auth tests, 14 distributors tests, 16 team tests, 15 business-profile tests, and 21 invoice tests). Tests run against a separate pharmaflow_test database. Each test truncates all tables at teardown to ensure isolation, so committed mutations in route handlers are fine.

Demo accounts

After running seed.py you can log in as any of three users on the same pharmacy to walk the role matrix:

Email	Role	Password	Sees
`vipul@vipulmedical.com`	OWNER	`password123`	Everything (expenses, analytics, team, settings).
`dharansh@email.com`	MANAGER	`password123`	Add Inventory, Returns, Past Invoices, generate invoices.
`ramesh@email.com`	STAFF	`password123`	Dashboard, Inventory browse, Generate Invoice, Settings.

The seeded business already has a complete profile + bank account so invoices and debit notes can be printed out of the box. Log in as an OWNER first and watch for the Management sidebar section; it narrows as you switch to MANAGER and disappears entirely for STAFF.

Setting up Google OAuth

To use Google Sign-In on the frontend:

Go to the Google Cloud Console
Create a new project (or use an existing one)
Navigate to APIs & Services > Credentials
Create an OAuth 2.0 Client ID (Application type: Web application)
Add http://localhost:5173 to Authorized JavaScript origins
Copy the Client ID and add it to both .env files:
- backend/.env as GOOGLE_CLIENT_ID
- frontend/.env as VITE_GOOGLE_CLIENT_ID

Backend Directory Structure

backend/
├── app/
│   ├── __init__.py            # Flask application factory + /api/uploads static route
│   ├── extensions.py          # SQLAlchemy & Migrate instances
│   ├── utils.py               # Shared parse/coerce helpers (date, expiry, int, float)
│   ├── auth/                  # register/login/me/change-password/google + profile picture
│   ├── business/              # /api/business profile + bank + completeness gate
│   ├── distributors/          # /api/distributors CRUD (settings-editor backing)
│   ├── team/                  # /api/team OWNER-only member CRUD + reactivation
│   ├── invoices/              # /api/invoices (412 completeness gate, createdBy audit)
│   ├── inventory/             # /api/inventory server-side filters
│   ├── receipts/              # /api/receipts (OCR + manual + approve)
│   ├── returns/               # /api/returns (debit notes)
│   ├── expense/               # /api/expenses + categories
│   ├── services/              # ocr_service (Google Cloud Vision integration)
│   └── models/
│       ├── __init__.py        # Re-exports all model classes
│       ├── user.py            # User, UserPasswordAuth, UserOAuthAccount
│       ├── business.py        # Business, BusinessMembership, BusinessBankAccount
│       ├── distributor.py     # Distributor
│       ├── customer.py        # Customer
│       ├── product.py         # Product
│       ├── inventory.py       # InventoryBatch, InventoryMovement
│       ├── purchase.py        # PurchaseReceipt, PurchaseReceiptItem, ReceiptScan
│       ├── sales.py           # SalesInvoice, SalesInvoiceItem, BatchAllocation
│       ├── expense.py         # ExpenseCategory, Expense
│       ├── returns.py         # ReturnRequest, ReturnRequestItem
│       ├── audit.py           # AuditLog
│       └── contact.py         # ContactMessage
├── migrations/                # Alembic migration versions
├── tests/                     # 250 tests (pytest) - see "Running Tests" below
│   ├── conftest.py            # Fixtures (seed_user returns OWNER with complete business)
│   ├── test_auth.py           # 39 tests incl. profile picture, must-change-password
│   ├── test_business.py       # 15 tests incl. completeness gate
│   ├── test_distributors.py   # 14 tests incl. rename-cascade + live-batch guard
│   ├── test_team.py           # 16 tests incl. soft-remove reactivation + last-owner guards
│   ├── test_invoices_inventory.py  # 21 tests incl. 412 gate + creator audit
│   ├── test_receipts_inventory.py  # 36 tests
│   ├── test_returns.py        # 30 tests
│   ├── test_expenses.py       # 9 tests
│   ├── test_ocr.py            # 22 tests (parser)
│   ├── test_models.py         # 42 model tests
│   └── test_seed.py           # 6 tests
├── docs/
│   ├── api-spec.yaml              # OpenAPI 3 - 44 paths, 56 schemas
│   ├── settings-architecture.md   # RBAC + team + distributors + profile picture (NEW)
│   ├── auth-architecture.md       # Auth primitives (JWT, decorators, password rotation)
│   ├── invoices-architecture.md   # FEFO allocation + completeness gate
│   └── inventory-architecture.md  # Stock / receipts / returns / OCR
├── uploads/                   # UPLOAD_DIR default - profiles/ + receipts/
├── config.py                  # Dev / Testing / Production configs
├── manage.py                  # Flask CLI entry point
├── seed.py                    # Sample data seeder (idempotent)
├── docker-compose.yml         # PostgreSQL 16 container
├── requirements.txt           # Python dependencies
├── .env                       # Local environment variables
└── .env.example               # Template for .env

Database Entity-Relationship Diagram (ERD)

The core architecture assumes a multi-tenant Business model where everything is scoped to a pharmacy. The diagram below illustrates the relationships between key entities:

erDiagram
    users ||--o{ business_memberships : "has"
    businesses ||--o{ business_memberships : "has"
    businesses ||--o{ products : "manages"
    businesses ||--o{ distributors : "partners with"
    businesses ||--o{ customers : "serves"
    businesses ||--o{ expenses : "incurs"
    businesses ||--o{ expense_categories : "defines"
    businesses ||--o{ sales_invoices : "issues"
    businesses ||--o{ purchase_receipts : "receives"
    businesses ||--o{ inventory_batches : "holds"
    businesses ||--o{ return_requests : "creates"
    businesses ||--o{ audit_logs : "tracks"

    distributors ||--o{ purchase_receipts : "supplies"
    distributors ||--o{ return_requests : "receives"
    distributors ||--o{ inventory_batches : "original source"

    customers ||--o{ sales_invoices : "pays"

    expense_categories ||--o{ expenses : "categorizes"

    purchase_receipts ||--o{ purchase_receipt_items : "contains"
    purchase_receipts ||--o| receipt_scans : "generated from"
    
    products ||--o{ purchase_receipt_items : "bought as"
    products ||--o{ sales_invoice_items : "sold as"
    products ||--o{ inventory_batches : "stocked as"
    products ||--o{ return_request_items : "returned as"

    purchase_receipt_items ||--o| inventory_batches : "creates"
    
    inventory_batches ||--o{ inventory_movements : "tracks history"
    inventory_batches ||--o{ sales_invoice_item_batch_allocations : "allocated to"
    
    sales_invoices ||--o{ sales_invoice_items : "contains"
    sales_invoice_items ||--o{ sales_invoice_item_batch_allocations : "fulfilled by"
    
    return_requests ||--o{ return_request_items : "contains"
    
    users ||--o{ audit_logs : "performs actions"

Backend Commands Reference

Command	Description
`docker compose up -d`	Start PostgreSQL container
`docker compose down`	Stop PostgreSQL container
`FLASK_APP=manage.py flask db migrate -m "msg"`	Generate a new migration
`FLASK_APP=manage.py flask db upgrade`	Apply pending migrations
`python seed.py`	Seed the database with sample data
`python -m pytest tests/ -v`	Run all tests with verbose output
`python -m pytest tests/ -v --cov=app`	Run tests with coverage report

Name		Name	Last commit message	Last commit date
Latest commit History 219 Commits
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

What is PharmaFlow?

Developer docs

Frontend Directory Structure

Key Architectural Details

Auth & Route Guards

Running the Frontend Locally

Prerequisites

Steps

Available Scripts

API Documentation

Backend - Flask + PostgreSQL

Backend Prerequisites

Backend Setup for Windows

Backend Setup for Linux

Running Tests for Linux

Running Tests for Windows

Demo accounts

Setting up Google OAuth

Backend Directory Structure

Database Entity-Relationship Diagram (ERD)

Backend Commands Reference

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

What is PharmaFlow?

Developer docs

Frontend Directory Structure

Key Architectural Details

Auth & Route Guards

Running the Frontend Locally

Prerequisites

Steps

Available Scripts

API Documentation

Backend - Flask + PostgreSQL

Backend Prerequisites

Backend Setup for Windows

Backend Setup for Linux

Running Tests for Linux

Running Tests for Windows

Demo accounts

Setting up Google OAuth

Backend Directory Structure

Database Entity-Relationship Diagram (ERD)

Backend Commands Reference

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages