pos/AGENTS.md

# AGENTS.md

## Project Overview

Build a full-stack TypeScript point-of-sale (POS) system packaged as a **single Docker container**: an Android tablet POS app talking to a Node/Express API, plus a React-based web admin UI served by the same backend.

The system must be offline-capable on the Android side, with the backend acting as the source of truth for vendors, catalog, and reporting when connectivity is available.

***

## Tech Stack

- **Backend API:** Node.js + TypeScript, Express or Fastify, REST API.
- **Web Admin UI:** React + TypeScript SPA, built and served as static assets by the Node backend.
- **Database (server-side):** SQL (PostgreSQL preferred; SQLite-in-Docker acceptable for early stages).
- **Android App:** Kotlin, MVVM, offline-first with Room/SQLite.
- **Containerization:** Single Docker image exposing one HTTP port; Node serves API under `/api` and React app under `/`.

***

## Roles

### Senior Full-Stack / Android-Adjacent Engineer

You are responsible for:

- Designing and implementing the Node/TypeScript backend: API contracts, data model, auth, and integration tests.
- Implementing the React/TypeScript admin UI: CRUD for vendors, catalog, roles, and reporting.
- Defining Android API contracts, offline sync endpoints, and data consistency rules with the Android engineer.
- Authoring the Dockerfile and runtime config for single-container deployment and local dev.


### Senior UI/UX Engineer

You are responsible for:

- Interaction design and UX flows for the Android POS and web admin.
- A reusable design system (tokens + components) that can be implemented in React and Android.
- UX for offline/online indicators, error recovery, and cashier-friendly flows.
- Delivering specs that make implementation straightforward (layouts, states, copy).

***

## Functional Scope

### Android POS App (Vendor-Facing)

MVP flows:

- Vendor/staff login and device binding.
- Product browsing (grid/list) with quick search and category filters.
- Cart management: add/remove items, adjust quantities, discounts, and notes.
- Payment screen: cash and “card via provider” (initially stubbed), handle success/fail/pending.
- Receipt screen: show summary and trigger print/email/SMS via backend hooks.
- Shift/daily summary screen: totals per user/device.

Offline behavior:

- All POS operations (catalog usage, cart, transaction finalize) must work offline using local storage.
- Background sync job to push transactions and pull catalog/price updates when online.
- Clear UI for connectivity state and sync status.


### Web Admin (Backoffice)

MVP features:

- Vendor onboarding and configuration (business details, tax settings).
- User management: create users, roles (cashier, manager, owner), and assign to vendors.
- Catalog: products, categories, pricing, taxes, and optional tags.
- Reporting: basic dashboards and tables for daily totals, sales by product, and tax summaries.

Admin UI uses the same API consumed by Android (no private backdoor logic).

***

## Backend Requirements

### API Design

- REST JSON API under `/api/v1`, with consistent error shapes and pagination.
- Use runtime validation (e.g., Zod) for all inputs and outputs; keep DTOs typed.
- Core resources: `vendors`, `users`, `roles`, `products`, `categories`, `prices`, `taxes`, `transactions`, `reports`.
- Auth: JWT access + refresh tokens; device association for Android clients.


### Data \& Persistence

- Use Prisma or TypeORM for TypeScript-friendly schemas and migrations.
- Design schemas to support:
    - Multi-vendor (multi-tenant) separation.
    - High write volume on `transactions`.
    - Reporting queries without extreme complexity.


### Android Integration Contracts

- Auth endpoints: login, refresh, logout.
- Sync endpoints:
    - `GET /api/v1/catalog/sync?since=...` for products, categories, taxes, etc.
    - `POST /api/v1/transactions/batch` for pushing local transactions with idempotency keys.
- Conflict handling strategy:
    - Server-authoritative for payments and refunds.
    - Catalog updates resolved by server with versioning.

***

## Docker \& Deployment

- Single Dockerfile with multi-stage build:
    - Stage 1: install deps, build backend and React admin.
    - Stage 2: copy built artifacts and minimal runtime deps, run Node server.
- Node server responsibilities:
    - Serve React static assets for non-`/api` routes.
    - Expose `/api` endpoints for Android and admin.
- Use environment variables for DB connection, JWT secret, and port configuration; document them in `README.md`.

***

## UI/UX Guidelines

- Design for 8–11" landscape Android tablets, touch-only, with large tap targets and minimal keyboard input.
- Optimize for transaction speed and error reduction at the counter.
- Provide explicit states and copy for: idle, in-cart, processing payment, payment failed, offline, syncing.
- Web admin should prioritize clarity and data density over heavy visual decoration.

***

## Process \& Collaboration

- Maintain `README.md`, `INSTRUCTIONS.md`, and `ROADMAP.md` as living documents; keep them aligned with the implementation.
- Work in vertical slices that cut across Android, API, and admin when feasible (e.g., “cash sale flow end-to-end”).
- For each new feature:
    - Define API contracts and schema changes first.
    - Confirm UX for happy path + edge cases.
    - Implement + test + update docs.

***

## Milestones

1. **Foundation**
    - Node/TS API skeleton, health check, auth stub.
    - React admin bootstrapped and served by Node.
    - Docker image builds and runs locally.
2. **Core Data \& Admin**
    - DB schema and migrations for vendors, users, catalog, transactions.
    - Auth and basic RBAC in backend and admin UI.
    - CRUD for catalog and users in admin.
3. **Android \& Offline Sync**
    - Define sync API and contract.
    - Android app implements offline-first flows and batch sync.
    - Admin reports show Android-originated transactions.
4. **Payments \& Hardening**
    - Abstraction for payments (provider-agnostic; start stubbed).
    - Better reporting, error handling, telemetry.
    - Production-ready Docker config and docs.