commit ab21fc1bbaf281e2a8ec5fc56a6a4fa0c95ec239 Author: jason Date: Fri Mar 20 22:49:17 2026 -0500 Add AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..94799f9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,157 @@ +# 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. \ No newline at end of file