Getting Started

Choose the application that matches your immediate goal, follow the setup steps below, then return here to map how the components connect.

Choose Your Starting Point

Start with SaleFlex.PyPOS

Your target is checkout operations, cashier workflows, and store-floor transactions. This is the most feature-complete component and the best place to begin evaluating the ecosystem.

Start with SaleFlex.OFFICE

Your target is back-office management — product catalog, campaign definitions, customer data, and local store reporting. Works alongside PyPOS or standalone.

Start with SaleFlex.GATE

Your target is building a multi-tenant central API, connecting multiple stores, or integrating third-party ERP / payment / loyalty systems.

SaleFlex.PyPOS Setup

Python 3.13+ · PySide6 · SQLite (default)

Prerequisites

Install Python 3.13 or higher (Python 3.14 is not yet officially supported by SQLAlchemy — use 3.13 for best compatibility)
Ensure pip is installed and up to date: pip install --upgrade pip
Git (to clone the repository)

Installation Steps

Clone the repository

git clone https://github.com/SaleFlex/SaleFlex.PyPOS.git
cd SaleFlex.PyPOS

Create and activate a virtual environment

python3 -m venv venv

# Windows
venv\Scripts\activate.bat

# macOS / Linux
source venv/bin/activate

Install dependencies

pip install -r requirements.txt

Run the application

python saleflex.py

The application initializes the SQLite database on first run and opens the login screen.

Default Login Credentials

Username	Password	Role
`admin`	`admin`	Administrator — can view/edit all cashier accounts and access Campaign Settings
`jdoe`	`1234`	Standard Cashier — can update own password only

Configuration

Edit settings.toml to configure the database connection, logging level, and integration mode:

# settings.toml (excerpt)
[database]
engine = "sqlite"        # or "postgresql", "mysql", etc.
path   = "db.sqlite3"

[logging]
level   = "INFO"         # DEBUG | INFO | WARNING | ERROR | CRITICAL
console = true
file    = true

[gate]
enabled          = false  # set true to connect to SaleFlex.GATE
manages_campaign = false  # delegate campaign evaluation to GATE

Many POS settings (hardware ports, display type, receipt printer) are managed through the database via Settings → POS Settings inside the application — no need to edit config files for those.

View Full Documentation on GitHub Watch Demo

SaleFlex.OFFICE Setup

Python · PySide6 · SQLAlchemy

Prerequisites

Python 3.11 or higher
pip available and up to date
Git (to clone the repository)

Installation Steps

git clone https://github.com/SaleFlex/SaleFlex.OFFICE.git
cd SaleFlex.OFFICE
pip install -r requirements.txt
python saleflex.py

What Happens on First Run

The StartupForm (splash screen) opens and displays bootstrap progress.
The BootstrapDataLoader creates the database and seeds all initial data (users, store, POS terminal, settings).
The LoginForm opens in fullscreen mode for credential entry.
On successful login, the ModuleLauncherForm lists all available management modules.

Default Login Credentials

Username	Password	Role
`admin`	`admin`	Administrator
`jdoe`	`1234`	Standard user
`jpace`	`1234`	Standard user

View on GitHub

SaleFlex.GATE Setup

Python 3.12+ · Django · Django REST Framework

Prerequisites

Python 3.12 or newer
pip available and up to date
Git (to clone the repository)
PostgreSQL (recommended for production; SQLite used by default in development)

Installation Steps

Clone and enter the directory

git clone https://github.com/SaleFlex/SaleFlex.GATE.git
cd SaleFlex.GATE

Create and activate a virtual environment

python -m venv .venv

# Windows
.venv\Scripts\activate.bat

# macOS / Linux
source .venv/bin/activate

Install dependencies and run migrations

pip install -r requirements.txt
python manage.py makemigrations
python manage.py migrate
python manage.py collectstatic --noinput

Create a superuser and start the server

python manage.py createsuperuser   # optional — for Django Admin
python manage.py runserver

Public site: http://127.0.0.1:8000/ · Django Admin: http://127.0.0.1:8000/admin/

Production note: Replace the development SECRET_KEY in gate_project/settings.py, set DEBUG = False, configure ALLOWED_HOSTS, and switch the database to PostgreSQL before any real deployment.

View on GitHub

Recommended Evaluation Flow

Review ecosystem concepts on this website

Use the Architecture page to understand layers and boundaries before touching code.

Run PyPOS locally and explore the demo

Follow the PyPOS setup above, log in as admin, and walk through Sales → Closure → Settings to understand the core workflow.

Open the repository documentation

Each repository has a docs/ folder with detailed guides — architecture, configuration, API, and module-level references.

Map integration boundaries to your use case

Decide which deployment profile fits your needs — standalone, office-connected, or gate-connected — and configure accordingly.