Add AGENTS.md
This commit is contained in:
157
AGENTS.md
Normal file
157
AGENTS.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user