diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7dee2e6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,159 @@
+# 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]