160 lines
3.4 KiB
Markdown
160 lines
3.4 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
# from /server
|
||
npm install
|
||
npm run dev # or equivalent, e.g. ts-node-dev / nodemon
|
||
```
|
||
|
||
Admin UI:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
docker build -t vendor-pos:latest .
|
||
```
|
||
|
||
|
||
### 2. Run the Container (Simple)
|
||
|
||
For a quick start with SQLite or an in-container DB:
|
||
|
||
```bash
|
||
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):
|
||
|
||
```yaml
|
||
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:
|
||
|
||
```bash
|
||
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]
|