Olgax POS

Open-source, offline-capable Point of Sale system — free forever for self-hosted deployments.

olgax.com · Discord Community · Getting Started · Architecture · Deployment · Contributing

---

What is Olgax POS?

Olgax POS is a fast, touch-friendly, fully offline-capable Point of Sale system built by OLGAX. It is designed to be good enough for real small businesses to use daily — for free, forever — while remaining extensible into a full-featured SaaS platform.

• Self-hosted — run it on your own server with Docker in minutes.
• Offline-first — uses PGLite (Postgres WASM) to record sales even with no internet, then syncs automatically when connectivity returns.
• Globally configurable — change your business name, logo, colors, currency, and tax settings from the UI.
• Open source — MIT licensed. Fork it, extend it, run it.

---

Features (v0.1 MVP)

Feature	Status
Product catalog (create / edit / delete)	✅
Barcode / keyboard product search	✅
Stock adjustment history with audit trail	✅
Supplier management	✅
POS checkout — cart, qty, discount, tax	✅
Split-tender payments (Cash + Card + Other)	✅
Hold & recall orders	✅
Void sale with reason	✅
Refund / partial refund support	✅
Tip support at checkout	✅
Receipt printing (ESC/POS thermal + browser fallback)	✅
Customer directory with purchase history	✅
Loyalty points (earn & redeem)	✅
Offline mode with auto-sync	✅
Admin + Cashier roles	✅
Business settings (logo, colors, currency, tax)	✅
Sales reports & CSV export	✅
Breadcrumb navigation on detail pages	✅
Docker Compose ready	✅
PWA / installable on tablet	✅

---

Quick Start (Docker — recommended)

# 1. Clone
git clone https://github.com/olgax/olgax-pos.git
cd olgax-pos

# 2. Configure secrets
cp .env.example .env
# Edit .env: set BETTER_AUTH_SECRET to a long random string

# 3. Start
docker compose up -d

# 4. Open in browser
open http://localhost:3000

The first time you open the app you will be guided through a setup wizard that migrates the database and creates your admin account.

---

Quick Start (Serverless — Vercel / Netlify)

You can run Olgax POS serverless without Docker or a VPS:

1. Fork or Use Template: Click Fork or Use this template at the top of this repository to create a copy in your own account.
2. Deploy: Import your copy into Vercel or Netlify.
3. Database: Use a managed database provider like Neon or Supabase (using a pooled DATABASE_URL and a direct DIRECT_URL).

See the Deployment Guide for detailed instructions.

---

Quick Start (Local Development)

Prerequisites: Node.js ≥ 20, pnpm ≥ 9, PostgreSQL ≥ 14

# 1. Clone & install
git clone https://github.com/olgax/olgax-pos.git
cd olgax-pos
pnpm install

# 2. Configure environment
cp .env.example .env
# Set DATABASE_URL and BETTER_AUTH_SECRET in .env

# 3. Migrate database
pnpm db:migrate

# 4. (Optional) Seed sample products
pnpm db:seed

# 5. Start dev server
pnpm dev

Open http://localhost:3000. A setup wizard will guide you through creating your admin account on first run.

---

Documentation

Document	Description
Getting Started	Full installation guide for all environments
Configuration	Environment variables, business settings, per-device settings
Architecture	Tech stack, project structure, data model
Deployment	Docker, reverse proxy, HTTPS, production checklist
API Reference	Internal REST API endpoints
Contributing	Development workflow, coding standards, PR guide

---

Tech Stack

• Framework: Next.js 16 App Router + TypeScript strict mode
• UI: shadcn/ui + Tailwind CSS 4
• Database: PostgreSQL + Prisma 7 ORM
• Offline DB: PGLite (Postgres WASM in the browser)
• Auth: Better Auth (email/password, role-based)
• State: Zustand (POS cart)
• Forms: react-hook-form + Zod validation
• Testing: Vitest + Playwright

---

Roadmap

The MVP (v0.1) is designed to be immediately useful for small businesses while laying clean groundwork for future features:

• Multi-language (next-intl)
• Multi-store / multi-location
• Customer directory + loyalty points
• Plugin system
• Advanced reports + charts
• Kitchen Display System (KDS)
• Hosted SaaS at olgax.app

See OLGAX Roadmap for the full picture.

---

License

MIT — see LICENSE for details.

Built with ❤️ by OLGAX