README.md

Overview

This project is a full-stack TypeScript point-of-sale (POS) system: an Android POS frontend, a Node/Express API backend, and a React admin UI, all packaged in a single Docker container.

The backend exposes REST APIs for the Android app and serves the React admin UI for vendor configuration and reporting.

---

Tech Stack

• Node.js + TypeScript (Express or Fastify)
• React + TypeScript (SPA)
• SQL database (PostgreSQL in production; SQLite acceptable for local/demo)
• Docker (single container for API + admin UI)

---

Project Structure

Example layout (subject to refinement):

• server/ – Node/TypeScript backend (Express/Fastify, Prisma, migrations)
• client/ – React/TypeScript admin UI
• android/ – Android POS app (separate repo or module)
• Dockerfile – single-image build for backend + admin
• docker-compose.yml – optional local DB wiring
• AGENTS.md, INSTRUCTIONS.md, ROADMAP.md – agent and project docs

---

Prerequisites

For local (non-Docker) runs:

• Node.js 20+ installed
• npm or pnpm
• PostgreSQL (or SQLite if configured)

For Docker runs:

• Docker Engine (and optionally Docker Compose)

---

Environment Variables

Backend expects:

• PORT – HTTP port (default: 8080)
• NODE_ENV – development or production
• DATABASE_URL – connection string (e.g., Postgres)
• JWT_SECRET – secret for JWT signing
• LOG_LEVEL – optional (info, debug, etc.)

Document any additional env vars you introduce in this section.

---

Local Development (Without Docker)

Backend:

# from /server
npm install
npm run dev   # or equivalent, e.g. ts-node-dev / nodemon

Admin UI:

# from /client
npm install
npm run dev   # Vite/CRA dev server

You can either:

• Run React dev server separately and point it at the API (VITE_API_URL=http://localhost:8080/api), or
• Configure the backend to serve the built React app in production mode.

---

Building & Running with Docker

1. Build the Image

From the project root:

docker build -t vendor-pos:latest .

2. Run the Container (Simple)

For a quick start with SQLite or an in-container DB:

docker run --rm -p 8080:8080 \
  -e NODE_ENV=production \
  -e PORT=8080 \
  -e DATABASE_URL=sqlite:./data.db \
  -e JWT_SECRET=change-me \
  vendor-pos:latest

The admin UI will be available at http://localhost:8080/ and the API at http://localhost:8080/api/....

3. Run with Postgres via Docker Compose (Optional)

Example docker-compose.yml (to be refined):

version: "3.9"
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: pos_user
      POSTGRES_PASSWORD: pos_password
      POSTGRES_DB: pos_db
    ports:
      - "5432:5432"
    volumes:
      - pos_db_data:/var/lib/postgresql/data

  app:
    image: vendor-pos:latest
    depends_on:
      - db
    ports:
      - "8080:8080"
    environment:
      NODE_ENV: production
      PORT: 8080
      DATABASE_URL: postgres://pos_user:pos_password@db:5432/pos_db
      JWT_SECRET: change-me

volumes:
  pos_db_data:

Then:

docker compose up

---

Android Integration (High Level)

• Android app calls http://<server>:8080/api/v1/... for auth, catalog sync, and transaction upload.
• All POS operations work offline; app syncs when network is available.[^11][^12][^10]
• The web admin UI is used for vendor setup, catalog maintenance, user management, and reports.[^20][^17]