POS System

English

Español

English

Español

Appearance

Installation ​

This guide walks you through setting up the POS system development environment from scratch. The project is organized as a monorepo managed with pnpm workspaces, with a Rust backend and TypeScript frontend applications.

Prerequisites ​

Before you begin, make sure the following tools are installed on your system:

  • Node.js version 20 or later. We recommend using fnm or nvm to manage Node versions.
  • Rust stable toolchain (1.75+). Install via rustup.
  • Docker and Docker Compose for running PostgreSQL and Redis containers.
  • pnpm version 9 or later. Install globally with npm install -g pnpm.

You can verify your setup by running:

bash
node --version    # v20.x or later
rustc --version   # 1.75.0 or later
docker --version  # 24.x or later
pnpm --version    # 9.x or later

Clone and Install ​

Clone the repository and install all dependencies:

bash
git clone https://github.com/your-org/pos.git
cd pos
pnpm install

The pnpm install command will install dependencies for all workspaces in the monorepo, including the frontend applications (POS Terminal, Store Manager, HQ Manager) and any shared packages.

Docker Services ​

The system requires PostgreSQL for data storage and Redis for caching and real-time event broadcasting. A docker-compose.yml file is provided at the root of the repository:

bash
docker compose up -d

This starts two containers:

  • PostgreSQL on port 5432 with default credentials pos:pos and a database named pos_hq.
  • Redis on port 6379 with no authentication.

You can verify the services are running with docker compose ps. Both containers should show a status of "running".

Database Setup ​

Once PostgreSQL is running, apply the database migrations:

bash
cd apps/hq-server
cargo run -- migrate

This creates all necessary tables, indexes, and seed data in the pos_hq database. The migration command is idempotent, so it is safe to run multiple times.

First Build ​

Build all frontend applications and the backend server:

bash
# Build the Rust backend
cd apps/hq-server
cargo build

# Build all frontend apps
cd ../..
pnpm build

If everything compiles without errors, your development environment is ready. Proceed to First Setup to create your admin account and configure the system.

Development Mode ​

For day-to-day development, you will typically run the backend and frontend in watch mode:

bash
# Terminal 1: Rust backend with auto-reload
cd apps/hq-server
cargo watch -x run

# Terminal 2: Frontend dev servers
pnpm dev

The frontend dev server provides hot module replacement, so changes to React components appear instantly in the browser without a full page reload.