HUB
Sign inSign up

omersx/pharmacy-erp

By omersx

•Updated 2 months ago

All-in-one image for Pharmacy ERP (Frontend, Backend & Proxy)

Image
0

1.0K

omersx/pharmacy-erp repository overview

Pharmacy ERP Logo

⁠Pharmacy ERP & POS System

A modern, open-source Pharmacy ERP & Point of Sale system built for independent pharmacies, chains, and hospitals.

Full Arabic (RTL) & English support · Designed for the Gulf/MENA market

License: MIT CI Docker npm Python 3.12+ Node.js 18+ FastAPI Next.js 15 PRs Welcome

Features⁠ · Quick Start⁠ · Screenshots⁠ · Architecture⁠ · API Docs⁠ · Docker⁠ · Contributing⁠


⁠✨ Features

⁠🏪 Point of Sale
  • Fullscreen, keyboard-first, touch-friendly POS
  • Hardware & Camera Barcode Scanning (USB/webcam/phone)
  • Auto-add to cart with audio/visual beep feedback
  • Hold & recall sales
  • Split payments (cash, card, credit)
  • Receipt printing (PDF export)
⁠💊 Medicine Management
  • Complete product catalog with categories
  • Batch tracking with expiry dates
  • FEFO (First Expiry, First Out) allocation
  • CSV/Excel bulk import
  • Low stock & expiry alerts
⁠📦 Inventory & Purchasing
  • Append-only inventory ledger
  • Real-time stock levels per branch
  • Purchase orders & goods receipt
  • Supplier management & tracking
  • Automated stock alerts
⁠💰 Sales & Cash Management
  • Sales invoices & returns
  • Cash session management (open/close)
  • Opening float & blind close
  • X-Report & Z-Report generation
  • Customer credit tracking
⁠📊 Reports & Analytics
  • Sales reports (daily, weekly, monthly)
  • Inventory valuation reports
  • Profit & margin analysis
  • Top-selling products
  • Exportable to Excel/PDF
⁠🌍 Enterprise Features
  • Bilingual: Full Arabic (RTL) + English
  • Dark/Light Theme: Premium UI design
  • RBAC: Role-based access control
  • Multi-branch: Branch management
  • Responsive: Desktop, tablet, & mobile

⁠📸 Screenshots

Coming soon — Screenshots of the Dashboard, POS, Inventory, and Reports pages will be added here.

Want to see the app in action? Follow the Quick Start⁠ guide to run it locally in under 5 minutes!


⁠🚀 Quick Start

⁠Prerequisites
ToolVersionDownload
Node.js18+nodejs.org⁠
pnpm9+npm install -g pnpm
Python3.12+python.org⁠

The easiest way to scaffold and start the project is using our interactive CLI:

# 1. Scaffold the project (clones, installs, and seeds data automatically)
npx pharmacy-erp init

# 2. Enter the directory
cd pharmacy-erp

# 3. Start the application
npx pharmacy-erp start
⁠Option B: Using Setup Scripts

If you prefer to clone manually, you can use our built-in setup scripts.

🪟 Windows
git clone https://github.com/omersx/pharmacy-erp.git
cd pharmacy-erp
start.bat
🐧 Linux / 🍎 macOS
git clone https://github.com/omersx/pharmacy-erp.git
cd pharmacy-erp
chmod +x start.sh
./start.sh
⁠Option C: Step-by-Step
# 1. Clone the repository
git clone https://github.com/omersx/pharmacy-erp.git
cd pharmacy-erp

# 2. Install root dependencies (concurrently)
pnpm install

# 3. Setup frontend
pnpm run setup:frontend

# 4. Setup backend (auto-detects Windows/Linux/macOS)
pnpm run setup:backend

# 5. Configure environment
cp .env.example .env   # Linux/macOS
# copy .env.example .env  # Windows

# 6. Seed demo data
pnpm run seed

# 7. Start development servers
pnpm dev
⁠🎉 You're Ready!
ServiceURL
🌐 Frontendhttp://localhost:3000⁠
🔧 Backend APIhttp://localhost:8000⁠
📚 API Docs (Swagger)http://localhost:8000/docs⁠
⁠Default Login
RoleUsername / EmailPassword
Super Adminadmin or [email protected]admin or admin123

⚠️ Change the default credentials before deploying to production!


⁠🏗️ Architecture

graph TB
    subgraph Client
        A[Browser] -->|HTTP/HTTPS| B[Next.js Frontend]
    end

    subgraph Frontend["Frontend — Next.js 15"]
        B --> C[App Router]
        C --> D[POS Module]
        C --> E[ERP Dashboard]
        C --> F[Auth Pages]
        B --> G[Zustand Store]
        B --> H[next-intl i18n]
    end

    subgraph Backend["Backend — FastAPI"]
        I[API Gateway] --> J[Auth & RBAC]
        I --> K[Medicines]
        I --> L[Inventory]
        I --> M[Sales & POS]
        I --> N[Purchases]
        I --> O[Customers]
        I --> P[Cash Sessions]
        I --> Q[Reports]
        I --> R[Admin & Audit]
    end

    subgraph Data["Data Layer"]
        S[(SQLite / PostgreSQL)]
    end

    B -->|REST API| I
    J --> S
    K --> S
    L --> S
    M --> S
    N --> S
    O --> S
    P --> S
    Q --> S
    R --> S
⁠Project Structure
pharmacy-erp/
├── frontend/                 # Next.js 15 (App Router)
│   ├── src/
│   │   ├── app/              # Routes & pages
│   │   │   └── [locale]/     # i18n routing (en, ar)
│   │   │       ├── (app)/    # ERP dashboard pages
│   │   │       ├── (auth)/   # Login / register
│   │   │       └── (pos)/    # Point of Sale
│   │   ├── components/       # Reusable UI components
│   │   │   ├── ui/           # Base components (Radix UI)
│   │   │   └── pos/          # POS-specific components
│   │   ├── lib/              # API client, utilities
│   │   ├── store/            # Zustand state stores
│   │   ├── messages/         # i18n translations (en.json, ar.json)
│   │   └── i18n/             # i18n configuration
│   ├── Dockerfile
│   └── package.json
│
├── backend/                  # FastAPI (Python 3.12)
│   ├── app/
│   │   ├── core/             # Config, database, security, exceptions
│   │   ├── modules/          # Business logic modules
│   │   │   ├── auth/         # Authentication & JWT
│   │   │   ├── users/        # User management
│   │   │   ├── roles/        # RBAC roles & permissions
│   │   │   ├── organizations/# Branch management
│   │   │   ├── medicines/    # Product catalog & batches
│   │   │   ├── inventory/    # Stock movements & ledger
│   │   │   ├── sales/        # Invoices, returns, held sales
│   │   │   ├── purchases/    # Purchase orders
│   │   │   ├── suppliers/    # Supplier management
│   │   │   ├── customers/    # Customer & credit management
│   │   │   ├── cash_sessions/# Cash register sessions
│   │   │   ├── reports/      # Analytics & reporting
│   │   │   ├── notifications/# System notifications
│   │   │   └── admin/        # Audit logs & admin tools
│   │   ├── main.py           # FastAPI application entry
│   │   └── seed.py           # Demo data seeder
│   ├── Dockerfile
│   └── requirements.txt
│
├── nginx/                    # Nginx reverse proxy config
├── img/                      # Logo and brand assets
├── docker-compose.yml        # Production deployment
├── package.json              # Root orchestration scripts
├── start.bat                 # One-click setup (Windows)
├── start.sh                  # One-click setup (Linux/macOS)
├── .env.example              # Environment template
└── README.md

⁠🖥️ Tech Stack

LayerTechnologies
FrontendNext.js 15⁠ · React 19⁠ · TypeScript⁠ · Tailwind CSS⁠
UI ComponentsRadix UI⁠ · Lucide Icons⁠ · Framer Motion⁠ · Recharts⁠
State & i18nZustand⁠ · next-intl⁠
BackendFastAPI⁠ · Python 3.12⁠ · Pydantic v2⁠ · SQLAlchemy 2⁠
DatabaseSQLite⁠ (dev) · PostgreSQL⁠ (production)
AuthJWT (httpOnly cookies) · Argon2⁠ password hashing
DevOpsDocker⁠ · Nginx⁠ · Uvicorn⁠

⁠📖 API Documentation

Once the backend is running, interactive API documentation is available at:

⁠API Modules
Endpoint PrefixModuleDescription
/api/v1/authAuthenticationLogin, register, refresh tokens
/api/v1/medicinesMedicinesCRUD, batches, categories, import
/api/v1/inventoryInventoryStock movements, alerts, ledger
/api/v1/salesSalesInvoices, returns, held sales
/api/v1/cash-sessionsCash SessionsOpen, close, X/Z reports
/api/v1/customersCustomersCustomer management, credit
/api/v1/suppliersSuppliersSupplier directory
/api/v1/branchesBranchesMulti-branch management
/api/v1/reportsReportsSales, inventory, profit analytics
/api/v1/usersUsersUser management
/api/v1/rolesRolesRBAC roles & permissions
/api/v1/adminAdminAudit logs, system admin
/api/v1/notificationsNotificationsSystem notifications

⁠🐳 Docker Deployment

⁠Quick Deploy (from Docker Hub)

The easiest way to run the entire system (Frontend, Backend, and Proxy) is using our official all-in-one image:

docker run -d \
  --name pharmacy-erp \
  -p 80:80 \
  omersx/pharmacy-erp:latest

This starts the entire application on port 80. You can now access it at http://localhost.

⁠Build from Source (for contributors)
docker compose -f docker-compose.dev.yml up --build
⁠Production Checklist
  • Change SECRET_KEY to a strong random value (32+ characters)
  • Change default admin credentials
  • Set APP_ENV=production and DEBUG=false
  • Switch database to PostgreSQL
  • Configure proper CORS_ORIGINS
  • Enable HTTPS via reverse proxy
  • Set up automated backups

⁠⚙️ Environment Variables

VariableDescriptionDefault
APP_NAMEApplication namePharmacy ERP
APP_ENVEnvironment (development / production)development
DEBUGEnable debug modetrue
DATABASE_URLDatabase connection stringsqlite+aiosqlite:///./data/pharmacy.db
SECRET_KEYJWT signing key (change in production!)dev-secret-key-...
ACCESS_TOKEN_EXPIRE_MINUTESAccess token TTL30
REFRESH_TOKEN_EXPIRE_DAYSRefresh token TTL7
CORS_ORIGINSAllowed CORS origins (comma-separated)http://localhost:3000
NEXT_PUBLIC_API_URLAPI URL for the frontendhttp://localhost:8000/api/v1
REDIS_URLRedis URL (optional, for production)—
UPLOAD_DIRFile upload directory./data/uploads
MAX_UPLOAD_SIZE_MBMax upload file size10

See .env.example⁠ for the full template.


⁠🌍 Internationalization

Pharmacy ERP ships with complete support for:

LanguageDirectionStatus
🇬🇧 EnglishLTR (Left-to-Right)✅ Complete
🇸🇦 العربية (Arabic)RTL (Right-to-Left)✅ Complete

Switch languages from any page — the entire UI, including layout direction, updates instantly.

Adding a new language:

  1. Create a new translation file: frontend/src/messages/<locale>.json
  2. Add the locale to frontend/src/i18n/ configuration
  3. All strings are externalized — no hardcoded text in components

⁠🤝 Contributing

We love contributions! Whether it's fixing bugs, adding features, improving docs, or suggesting ideas — all contributions are welcome.

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'feat: add amazing feature'
  4. Push to the branch: git push origin feature/amazing-feature
  5. Open a Pull Request

Please read our Contributing Guide⁠ and Code of Conduct⁠ before getting started.


⁠🗺️ Roadmap

  • 📱 Mobile app (React Native)
  • 📊 Advanced analytics dashboard
  • 🏥 Insurance claims module
  • 💳 Payment gateway integration
  • 📧 Email notifications & alerts
  • 🔄 Real-time sync across branches
  • 📋 Prescription management
  • 🧪 Lab integration module

Have a feature idea? Open a feature request!⁠


⁠⭐ Show Your Support

If this project helps you, give it a ⭐ on GitHub — it means a lot and helps others discover it!


⁠📄 License

This project is licensed under the MIT License — see the LICENSE⁠ file for details.


Built with ❤️ for pharmacies everywhere

Report Bug⁠ · Request Feature⁠ · Contribute⁠

Tag summary

Content type

Image

Digest

sha256:ad02f9bb5…

Size

172.3 MB

Last updated

2 months ago

docker pull omersx/pharmacy-erp