Imported from twichai/pos-monkey-ui (
AGENTS.md). Install upstream withnpx skills add twichai/pos-monkey-ui. Copyright stays with the author.
POS Monkey UI — Agent Guidelines
Next.js 16 + React 19 + shadcn/ui + TypeScript
For POS Back Office Management System
This agent builds a clean, scalable Next.js frontend for a full POS Back Office system.
The frontend focuses on dashboards, product management, stock control, staff roles, branches, reporting, and integration settings.
All business logic, validation rules, and data operations are handled exclusively by backend APIs (REST + Axios).
The agent outputs production-grade UI, typed Axios API clients, and components built with shadcn/ui blocks (prefer pre-built blocks over raw Tailwind), fully i18n-ready.
Table of Contents
- Purpose & Scope
- Back Office Modules
- Tech Stack
- Project Structure
- Coding Standards
- API Integration (Axios)
- Component Patterns
- State Management
- Styling Guidelines
- Internationalization (i18n)
- Error Handling
- Testing
- Performance
- Code Examples
1. Purpose & Scope
The goal of this agent is to implement the Back Office for a POS system.
The Back Office contains all administrative functions, such as:
- Product & Category Management
- Add-ons, Variants, Modifiers
- Pricing rules and Taxes
- Stock Management & Stock History
- Branch Management
- User/Staff Roles & Permissions
- Sales Channels (GrabFood, ShopeeFood, LINE MAN, etc.)
- Reports & Dashboards
- Receipt Layout settings
- Table Layout & Floor Plan (for restaurants)
- Integration settings (Printers, Payment Gateways, Webhooks)
✅ In Scope
| Area | Description |
|---|---|
| UI Development | Build pages & components with Next.js App Router |
| Styling | shadcn/ui blocks first, minimal raw Tailwind |
| API Consumption | REST calls via typed Axios clients |
| Type Safety | Strict TypeScript throughout |
| i18n | Full internationalization support |
| UX States | Loading, empty, error, and success states |
| Responsive Design | Tablet + Desktop layouts |
| Form Validation | Client-side validation with Zod/Yup |
❌ Out of Scope
- POS front-end order-taking UI
- Local printer logic (handled by backend bridge/device service)
- Server-side validation/business rules
- Database models or schema design
- Authentication logic (frontend only receives tokens)
- Backend/API development
2. Back Office Modules
The agent must support the following POS Back Office modules:
2.1 Product Management
| Feature | Description |
|---|---|
| Items | Create, edit, delete products with images |
| Categories | Organize products into hierarchical categories |
| Variants | Size, color, and custom variant options |
| Modifiers & Add-ons | Add-on groups, modifier pricing |
| Channel Pricing | Sales price rules per channel (dine-in, delivery) |
| Barcode/PLU | SKU and barcode management |
| Stock Visibility | Real-time stock levels display |
2.2 Stock & Inventory
| Feature | Description |
|---|---|
| Stock Card | Movement history per product |
| Stock-in/out | Record stock movements |
| Adjustments | Stock corrections and write-offs |
| Low-stock Alerts | Threshold-based notifications |
| Branch Stock | Real-time stock by location |
2.3 Branch & Staff
| Feature | Description |
|---|---|
| Branch List | Multi-location management |
| Opening Hours | Business hours per branch |
| Staff Roles | Permission matrix and access control |
| Activity Logs | Audit trail for staff actions |
2.4 Orders & Reports
| Feature | Description |
|---|---|
| Summary Reports | Daily/weekly/monthly summaries |
| Sales by Branch | Location-based analytics |
| Top Products | Best sellers and trends |
| Payment Reports | Payment method breakdown |
| Export | Excel/CSV data export |
2.5 Settings & Integrations
| Feature | Description |
|---|---|
| Tax Settings | Tax rates and rules |
| Receipt Builder | Customize receipt templates |
| POS Terminals | Device configuration |
| KDS Routing | Kitchen display routing rules |
| Delivery Channels | GrabFood, ShopeeFood, LINE MAN integration |
| Table Layout | Floor plan and table management (restaurants) |
| Payment Gateways | Payment provider settings |
| Webhooks | External system notifications |
3. Tech Stack
| Category | Technology | Version |
|---|---|---|
| Runtime | Bun | latest |
| Framework | Next.js (App Router) | 16.x |
| UI Library | React | 19.x |
| Language | TypeScript | 5.x (strict) |
| Components | shadcn/ui + shadcn/ui blocks | latest |
| Styling | Tailwind CSS (minimal) | 4.x |
| HTTP Client | Axios | latest |
| i18n | next-intl | latest |
| Validation | Zod or Yup | latest |
| Layout | Responsive (tablet + desktop) | — |
Bun Commands
# Install dependencies
bun install
# Linting
bun lint
# Add a package
bun add <package-name>
# Add a dev dependency
bun add -d <package-name>
# Remove a package
bun remove <package-name>
# Update packages
bun update4. Coding Standards
Naming Conventions
| Type | Convention | Example |
|---|---|---|
| Components | PascalCase | ProductCard.tsx |
| Hooks | camelCase with use prefix |
useProducts.ts |
| Utils | camelCase | formatCurrency.ts |
| Types/Interfaces | PascalCase | Product, ApiResponse<T> |
| Constants | UPPER_SNAKE_CASE | API_BASE_URL |
| Files | kebab-case or PascalCase | product-card.tsx or ProductCard.tsx |
Quick Reference
| Task | Location | Pattern |
|---|---|---|
| API calls | lib/api/*.ts |
Typed Axios modules |
| SWR hooks | lib/api/swr/*.ts |
Data fetching with caching |
| Types | lib/types/*.ts |
Interfaces & DTOs |
| UI Components | components/ui/* |
shadcn/ui blocks, minimal custom Tailwind |
| Pages | app/**/page.tsx |
Server components when possible |
| Interactive UI | app/**/*.tsx |
Client components with "use client" |
| Translations | i18n/*.json |
Nested keys by feature |
| Utils | lib/utils/*.ts |
Pure functions |
Styling Guidelines
✅ Prefer shadcn/ui blocks
- Use pre-built shadcn/ui blocks from ui.shadcn.com/blocks for common patterns (tables, forms, cards, dialogs)
- Compose with shadcn/ui primitives (Button, Input, Card, Table, etc.)
- Minimize raw Tailwind — only use for spacing adjustments or layout tweaks
- Use
cn()utility for conditional classes
❌ Avoid
- Writing complex Tailwind class strings when a shadcn block exists
- Custom styling that duplicates shadcn/ui functionality
- Inline styles
11. Error Handling
Ready to build? Start with:
- Define your types in
lib/types/ - Create API client in
lib/api/ - Build UI components in
components/ - Compose pages in
app/