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.