Specification

Document Info

Version	1.3
Author	Nexpando
Last Updated	February 2026
Strategy	F&B + Retail | Build | Freemium
Reference	Market Research

Table of Contents

Overview

• Executive Summary
• Release Roadmap
• Freemium Tier Definition

Modules

1. Security & Access
2. Data Handling & Foundation
3. Payment Gateway (VNPAY Integration)
4. SELL Core System
5. Purchase System
6. Marketing System
7. API Gateway
8. Admin Portal (BO)
9. Client Portal
10. Artificial Intelligence Integration

Appendices

• A. Competitor Quick Reference
• B. Technology Stack
• C. Document History

Executive Summary

Strategic Positioning

                    Feature Depth
                         ▲
                         │
              Haravan    │    CukCuk
            (E-commerce) │    (F&B depth)
                         │         ★ OUR TARGET
                         │           (F&B + Retail + Offline-First)
         ────────────────┼────────────────────────►
                         │                    Vertical Focus
              KiotViet   │    iPOS
            (Broad SMB)  │  (Restaurant)
                         │

Key Differentiators

Differentiator	Competitor Gap	Our Advantage
Offline-First	All competitors ⚠️ weak	Full local-first architecture
F&B + Retail	CukCuk weak retail, KiotViet weak F&B	Dual vertical depth
AI Integration	Only MISA has voice	Predictive analytics, smart recommendations

Release Roadmap

Phase Overview

Release	Timeline	Focus	Effort
R1 - MVP	Months 1-4	Core POS + F&B essentials	40%
R2 - Core+	Months 5-7	Admin + Compliance + Reports	25%
R3 - Growth	Months 8-10	Online + Marketing	20%
R4 - Differentiation	Months 11-14	AI + Advanced	15%

Release 1 - MVP (Months 1-4)

Module	Features	Competitor Benchmark
1. Security & Access	Auth, basic roles	All have
3. Payment Gateway	Cash, VietQR, VNPAY, PhonePOS	All have (PhonePOS is differentiator)
4. SELL Core	Products, Categories, Inventory, BOM	KiotViet, CukCuk
4.12 Table Management	Floor plan, merge/split	CukCuk ✅, iPOS ✅
4.13 KDS	Kitchen display, routing	CukCuk ✅, iPOS ✅
4.9 E-Invoice	Decree 70/2025 compliance	Mandatory
5. Purchase System	Cart, Orders, Payments	All have
2.6 Offline Sync	Local-first, background sync	None - our advantage

Release 2 - Core+ (Months 5-7)

Module	Features	Competitor Benchmark
2. Data Handling	Logging, Config, Notifications	All have
4.10 Financial Mgmt	Revenue, Reconciliation	MISA leads
8. Admin Portal	Dashboard, Product mgmt, Orders	All have
2.3 Reporting	Sales, Inventory, Financial	KiotViet 80%

Release 3 - Growth (Months 8-10)

Module	Features	Competitor Benchmark
9. Client Portal	Web ordering, Customer accounts	Haravan leads
7. API Gateway	Load balancing, Rate limiting	Enterprise need
6. Marketing	Vouchers, Loyalty	Haravan 80%
4.14 QR Ordering	Scan-to-order	CukCuk ✅

Release 4 - Differentiation (Months 11-14)

Module	Features	Competitor Benchmark
10. AI Integration	Assistant, Recommendations	MISA voice only
Advanced Analytics	Forecasting, Predictions	None - gap

Freemium Tier Definition

Feature	Free (Micro)	Pro (SMB)	Enterprise
Limits
SKU limit	100	1,000	Unlimited
Locations	1	3	Unlimited
Users	1	5	Unlimited
Transactions/month	500	5,000	Unlimited
Core Features
Basic POS (cash/QR)	✅	✅	✅
E-invoice (Decree 70)	✅	✅	✅
Basic inventory	✅	✅	✅
Basic reports	✅	✅	✅
F&B Features
Table management	❌	✅	✅
KDS	❌	✅	✅
BOM/Recipe	❌	✅	✅
QR ordering	❌	✅	✅
Advanced
Inventory alerts	❌	✅	✅
Multi-location	❌	❌	✅
Vouchers/Loyalty	❌	✅	✅
Advanced analytics	❌	❌	✅
Client Portal	❌	❌	✅
AI Assistant	❌	❌	✅
API access	❌	❌	✅
Pricing	Free	299K/mo	Custom

Competitor Reference:

• KiotViet: Free tier, Standard 200K, Pro 400K
• MISA: Free (2M licenses), Standard 100K, Pro 250K
• CukCuk: No free tier, Basic 150K, Standard 300K

1. Security & Access

Release: R1 (MVP) | Priority: Must Have

Implementation Status

Package: @nx/identity | Framework: IGNIS (Hono + Drizzle ORM)

• Authentication: JWT with Bun.password (Argon2id) hashing
• 5 built-in roles: super-admin (100), admin (200), owner (300), employee (400), customer (897)
• Customer Management: Merchant-scoped customer CRUD with automatic role assignment
• WebSocket event broadcasting for seller registration
• See Identity Service for technical details.

Competitor Reference: All competitors have basic auth; KiotViet and Haravan have advanced RBAC

1.1 Authentication

Description: Secure user identity verification supporting multiple authentication methods with session management and account security controls.

• Credential Authentication: Username/password login with secure password hashing and brute-force protection (account lockout after failed attempts)
• Token-Based Sessions: JWT access tokens for API authorization with refresh token rotation for extended sessions
• Multi-Factor Authentication: Optional OTP via email/SMS for sensitive operations and high-risk accounts
• Email Verification: New account email confirmation flow with expiring verification links
• Session Controls: Concurrent session limits, remote logout, and token revocation on password change

Feature	KiotViet	Haravan	Our Target
Username/Password	✅	✅	✅
Phone OTP	✅	✅	✅
MFA	⚠️	✅	✅
SSO	❌	⚠️	✅ (Enterprise)

1.2 Authorization

Description: Role-Based Access Control (RBAC) with granular permissions at resource and action levels, supporting multi-tenant isolation.

• Role Management: Create custom roles per merchant with descriptive names and permission bundles (e.g., Cashier, Manager, Inventory Staff)
• Permission Granularity: Fine-grained permissions as resource:action pairs (e.g., product:create, order:refund, report:export)
• Role Assignment: Assign multiple roles to users; permissions are aggregated across all assigned roles
• Built-in Roles: Pre-configured system roles (Owner, Admin, Staff) with sensible defaults for quick onboarding
• Tenant Isolation: Users can have different roles across different merchants/locations they belong to

1.3 User Management

Description: Complete user lifecycle management from registration to deactivation, with profile management and multi-tenant support.

• User Profiles: Store personal information (name, phone, email, avatar), preferences, and notification settings
• Account Status: Active, suspended, or locked states with admin-controlled status transitions
• Employee Records: Link users to employee profiles with job title, department, hire date, and employment status
• Multi-Merchant Access: Single user account can access multiple merchants with different roles per merchant
• User Settings: Per-user configuration for language, timezone, default location, and UI preferences

1.4 Customer Management - NEW

Release: R1 | Priority: Must Have

Implemented

Controller: /customers (8 endpoints) | Service: CustomerService See Customer Management for API details.

Description: Merchant-scoped customer lifecycle management with automatic user provisioning and role assignment.

• Customer CRUD: Create, list, update, and delete customers with merchant-scoped access control
• Automatic Provisioning: Creating a customer automatically creates User + UserProfile + assigns customer role (897) + establishes merchant UserMapping in a single transaction
• Merchant Isolation: Customers created by Merchant A are not visible to Merchant B
• Bulk Operations: Bulk delete customers with merchant-scoped filtering
• Search & Filter: List customers with pagination, count endpoints, and findOne for specific lookups

1.5 Device Management

Description: Register, monitor, and control POS terminals and mobile devices across all merchant locations.

• Device Registration: Pair devices to merchant accounts via QR code scan or activation PIN
• Device Inventory: Track device type, model, OS version, app version, and hardware identifiers
• Status Monitoring: Real-time online/offline status with last activity timestamp and heartbeat tracking
• Remote Control: Push configuration updates, force logout, or remotely wipe device data
• Location Binding: Optionally restrict devices to specific store locations for security

2. Data Handling & Foundation

Release: R1 (Offline Sync) + R2 (Others) | Priority: Must Have

2.1 Logging & Auditing

Release: R2

Description: Comprehensive audit trail system recording all user actions for compliance, debugging, and business analytics.

• Action Logging: Capture create/update/delete operations with before/after data snapshots
• User Attribution: Every action linked to user ID, device, IP address, and timestamp
• Log Categories: Separate streams for authentication, transactions, inventory, and admin actions
• Compliance Retention: 10-year retention for financial transactions per Decree 70/2025 requirements
• Search & Export: Query logs by date range, user, action type, or resource; export to CSV/Excel

2.2 Configuration Management

Release: R2

Description: Centralized settings management with hierarchical overrides from system to merchant to user level.

• Setting Scopes: System-wide defaults, merchant-specific overrides, and per-user preferences
• Feature Flags: Toggle features on/off per merchant for gradual rollout or A/B testing
• Config Categories: Tax settings, receipt templates, payment methods, notification preferences, UI themes
• Change History: Track who changed what settings and when, with rollback capability
• Real-time Sync: Configuration changes propagate to all connected devices within seconds

2.3 Reporting & Analytics

Release: R2

Competitor Reference: KiotViet 80%, Haravan 85%, CukCuk 70%

Description: Business intelligence platform with real-time dashboards, customizable reports, and data export capabilities.

• Dashboard Widgets: Customizable KPI cards showing revenue, orders, top products, and staff performance
• Report Builder: Pre-built report templates plus custom report creation with drag-drop field selection
• Time Comparisons: Compare current period vs previous period/same period last year
• Drill-Down Analysis: Click through from summary to detailed transaction-level data
• Multi-Location Rollup: Aggregate reports across locations or filter by specific store/terminal
• Scheduled Reports: Auto-generate and email reports daily/weekly/monthly to stakeholders
• Export Formats: Download as Excel, PDF, or CSV; Excel exports preserve formulas for further analysis

Report Type	KiotViet	Haravan	CukCuk	Our Target
Sales summary	✅	✅	✅	✅
By product	✅	✅	✅	✅
By staff	✅	✅	✅	✅
By time period	✅	✅	✅	✅
Inventory reports	✅	✅	⚠️	✅
Financial reports	✅	✅	⚠️	✅
Custom reports	⚠️	✅	❌	✅
Export (Excel/PDF)	✅	✅	✅	✅

2.4 File/Media Management

Release: R2

Description: Unified asset management for product images, documents, receipts, and media files with optimization and CDN delivery.

• Upload Handling: Drag-drop or camera capture for images; support for JPEG, PNG, WebP, PDF up to 10MB
• Image Processing: Auto-resize and compress product images; generate thumbnails for listings
• Storage Organization: Files organized by merchant, category (products, receipts, documents)
• CDN Delivery: Serve images via CDN for fast loading on POS terminals and web
• Meta-Links: Associate files with products, orders, or other entities via flexible linking system
• Bulk Operations: Upload multiple product images at once; bulk download for backup

2.5 Notification System

Release: R2

Description: Multi-channel notification delivery for transactional alerts, marketing campaigns, and system announcements.

• Channels: Email, SMS, push notifications (mobile/desktop), and in-app notification center
• Transactional Triggers: Auto-send on order confirmation, payment received, delivery status, low stock alerts
• Template Engine: Customizable templates with merge fields (customer name, order details, amounts)
• Delivery Tracking: Track sent/delivered/read status; retry failed deliveries automatically
• Preference Management: Users control which notifications they receive and via which channels
• Batch Sending: Schedule bulk notifications for promotions or announcements

Note: Consolidates mailing functions from SELL Core (4.8), Purchase System (5.5), and Marketing (6.3) into a single shared service.

2.6 Offline Synchronization - NEW

Release: R1 (MVP) | Priority: Must Have | Differentiator

Competitor Reference: ALL COMPETITORS WEAK ⚠️ - This is our competitive advantage

Competitor	Offline Capability	Implementation
KiotViet	⚠️ Basic	Transactions only, no full sync
Haravan	⚠️ Basic	Limited, web-dependent
CukCuk	⚠️	F&B offline partial
iPOS	⚠️	Restaurant offline partial
MISA	⚠️	Basic only
Ours	✅ Full	Local-first architecture

Description: Build a robust offline-first architecture that ensures full POS functionality without internet connectivity, with intelligent background synchronization when connection is restored.

• Local-First Database: All critical data (products, prices, customers, pending orders) stored locally on device
• Offline Transactions: Complete POS operations without internet - sales, inventory adjustments, customer lookup
• Background Sync: Automatic synchronization when connection restored, with progress indicators
• Conflict Resolution: Smart merge strategies for concurrent edits (last-write-wins, manual resolution for conflicts)
• Sync Queue Management: Persistent queue of pending changes with retry logic
• Status Indicators: Clear UI showing online/offline state and sync progress

Why This Matters:

• Vietnam has unreliable internet in rural/suburban areas
• Peak business hours often coincide with network congestion
• Competitor analysis identifies this as Top 4 opportunity with High urgency

3. Payment Gateway (VNPAY Integration)

Release: R1 (MVP) | Priority: Must Have

Competitor Reference: All competitors support VNPay, MoMo, ZaloPay

3.1 CASH / QR / CARD / PhonePOS VNPAY Payment Integration

Description: A payment solution that integrates:

• CASH - Traditional cash handling with drawer management
• QR code - VietQR, VNPAY QR, MoMo, ZaloPay
• CARD - Credit/Debit via VNPAY terminal
• PhonePOS - VNPAY's Apple Pay-like contactless payment solution (NFC tap-to-pay)

Integrate with VNPAY Payment SDK for seamless App-to-App payment flows.

• Split Payments: Accept multiple payment methods on single transaction (e.g., 50% cash + 50% card)
• Offline Payments: Queue payment transactions when offline; process automatically when back online
• Payment Reconciliation: Auto-match payments with orders; flag discrepancies for review
• Tip Handling: Optional tip prompt with preset amounts or custom entry
• Cash Drawer: Track cash drawer balance; require count at shift open/close

Payment Method	KiotViet	Haravan	CukCuk	Our Target
Cash	✅	✅	✅	✅
VietQR	✅	✅	✅	✅
VNPAY QR	✅	✅	✅	✅
MoMo	✅	✅	✅	✅
ZaloPay	✅	✅	⚠️	✅
Card terminal	✅	✅	✅	✅
PhonePOS (NFC)	❌	❌	❌	✅
Split payment	⚠️	⚠️	✅	✅
Offline payment	⚠️	⚠️	⚠️	✅

PhonePOS Advantage: VNPAY PhonePOS enables merchants to accept contactless payments directly on their smartphones without additional hardware. This Apple Pay-like experience differentiates us from competitors and reduces merchant hardware costs.

4. SELL Core System

Release: R1 (MVP) | Priority: Must Have

4.1 Organization Management

Description: This function provides tools to set up and manage the organizational structure, including defining business units, branches, or related partners, to establish a clear hierarchy for sales and management operations.

• Organization Definition and Hierarchy: Allows the creation, editing, and hierarchy of organizational units (e.g., Parent Company, Branch, Store, Warehouse) in the system.
• Region and Area Management: Assigns organizational units to specific geographic areas to support distribution, sales management, and reporting by location.

4.2 Merchant Management

Description: This function focuses on registering, managing profiles, and maintaining partnerships with Merchants (sellers/business units) participating in the POS system or sales platform.

• Merchant Profile: Manage Merchant details, including legal information, contact information, and contract-related documents.
• Finance & Discount Setup: Define payment terms, applicable discount rates, and configure bank account information.
• Status and Activation: Manage Merchant activity status (active, suspended, locked).

4.3 Product Management

Competitor Reference: KiotViet 85%, Haravan 90%, CukCuk 70%

Description: Responsible for managing the entire product information lifecycle, from creating new products, defining attributes, to updating prices and sales status on different channels.

• Product Definition: Allows inputting and editing basic product information (SKU, name, description, image), and managing product variants (e.g., size, color).
• Price and Tax Management: Set up standard and promotional prices, and configure tax rates for each product or product category.
• Sales Channel Configuration: Defines which products are allowed to be displayed and sold on different channels (e.g., POS, Web Channel).

Feature	KiotViet	Haravan	CukCuk	Our Target
Basic product info	✅	✅	✅	✅
Variants (size/color)	✅	✅	⚠️	✅
Product images	✅	✅	✅	✅
Barcode/SKU	✅	✅	✅	✅
Multiple price lists	✅	✅	⚠️	✅
Tax configuration	✅	✅	✅	✅
Channel assignment	⚠️	✅	⚠️	✅
Bulk import/export	✅	✅	⚠️	✅

4.4 Category Management

Description: Provides the ability to organize and categorize products logically through the creation and management of categories and subcategories.

• Category Structure: Allows creation, editing, and management of the hierarchy of product categories (parent and child).
• Product Classification: Assign products to one or more related categories.
• Category Attribute Management: Set up separate attributes and filters for each category.

4.5 Inventory Management

Competitor Reference: KiotViet 85%, Haravan 90%, CukCuk 70%

Description: This function is responsible for tracking real-time inventory quantities at storage locations (warehouses, stores).

• Location Inventory Tracking: Track accurate inventory quantities for each SKU at different warehouses or points of sale.
• Inventory Adjustment & Counting: Supports manual inventory adjustments (e.g., loss, damage) and periodic inventory processes.
• Inventory Alerts: Set up automatic alert thresholds when inventory quantities reach minimum or maximum levels.

Feature	KiotViet	Haravan	CukCuk	Our Target
Multi-location tracking	✅	✅	⚠️	✅
Stock adjustments	✅	✅	✅	✅
Stock counting	✅	✅	⚠️	✅
Low stock alerts	✅	✅	⚠️	✅
Stock transfer	✅	✅	⚠️	✅
Batch/lot tracking	⚠️	✅	❌	✅
Expiry tracking	⚠️	⚠️	⚠️	✅
Offline inventory	⚠️	⚠️	⚠️	✅

4.6 Fare & Pricing System

Implementation Status

Package: @nx/pricing (extracted from @nx/commerce into standalone service)

• 9 controllers: Promotions, PromotionMethods, Rules, Fares, FareSets, Costs, Taxes, TaxSets, TaxTypes
• 7 services: 4 calculation + 3 management
• Polymorphic Rule engine (belongs to Fare, Promotion, or PromotionMethod)
• See Pricing Service for technical details.

Description: Flexible pricing engine supporting multiple price lists, dynamic rules, cost tracking, and promotional discounts.

• Multiple Price Lists: Create separate price lists for retail, wholesale, VIP, staff discount, or channel-specific pricing
• Fare Sets: Group related prices (e.g., "Happy Hour", "Weekend Special") for easy activation/deactivation
• Pricing Rules: Conditional pricing based on quantity tiers, customer segments, time of day, or location
• Cost Tracking: Record product costs from purchase orders; calculate real-time margins per product
• Price Scheduling: Set future price changes to activate automatically on specified dates
• Price History: Full audit trail of all price changes with timestamp and user attribution
• Currency & Rounding: Handle VND with configurable rounding rules (round to nearest 100/500/1000)

4.6.1 Promotions Engine - NEW

Implemented

Fully operational in @nx/pricing with REST API.

Description: Discount campaign system with configurable methods and conditional rules for targeted promotions.

• Promotion Types: Standard discounts (STANDARD) and buy-X-get-Y offers (BUY_GET)
• Promotion Lifecycle: DRAFT → ACTIVATED → DEACTIVATED / EXPIRED → ARCHIVED
• Promotion Methods: Fixed amount (FIXED) or percentage (PERCENTAGE) discounts targeting items, order total, or shipping
• Allocation Methods: Apply discount to each qualifying item (EACH), spread across items (ACROSS), or apply once (ONCE)
• Polymorphic Rules: Conditional logic (time, quantity, channel, custom) attachable to Fares, Promotions, or PromotionMethods
• Time-Based Activation: Schedule promotions with start/end timestamps for automatic activation/expiry

Feature	Planned	Implemented
Fare Sets & Fares	✅	✅
Conditional Rules (time/qty/channel)	✅	✅
Cost Tracking	✅	✅
Tax Management	✅	✅
Promotions (Standard)	✅	✅
Promotions (Buy X Get Y)	✅	✅
Promotion Methods (Fixed/Percentage)	✅	✅
Price Scheduling	✅	Planned
Price History / Audit Trail	✅	Planned

4.7 Search Engine

Release: R2 (Basic) / R3 (Advanced)

Description: Fast, typo-tolerant search powered by Typesense for instant product lookup, barcode scanning, and global search.

• Instant Search: Sub-50ms response times with type-ahead suggestions as user types
• Fuzzy Matching: Tolerate typos and misspellings (e.g., "cofee" finds "coffee")
• Multi-Collection Search: Search across products, categories, customers, and orders from single query
• Barcode/SKU Lookup: Instant exact-match lookup for barcode scanner input
• Faceted Filters: Filter results by category, price range, stock status, brand
• Synonyms: Configure product synonyms (e.g., "soda" = "soft drink" = "nước ngọt")
• Search Analytics: Track popular searches, zero-result queries for catalog improvement
• Real-time Indexing: Product changes reflected in search within seconds via change data capture

4.8 Transactional Email

Release: R2

Description: Automated email capabilities to support core business functions such as transaction notifications and order confirmations.

Note: Merged into unified Notification System (2.5). This section retained for backwards compatibility.

4.9 External Integration

Release: R1 (E-Invoice) + R2 (Others)

4.9.1 E-Invoice Integration - Decree 70/2025 (CRITICAL)

Release: R1 (MVP) | Priority: MUST HAVE - Regulatory Requirement

Competitor Reference: All competitors compliant - this is table stakes

Competitor	E-Invoice	Provider(s)	Notes
KiotViet	✅	VNPT, Viettel	30% discount program
Haravan	✅	VNPT, FPT	Multiple options
CukCuk	✅	MISA meInvoice	Native MISA integration
iPOS	⚠️	Various	Certified
MISA	✅	meInvoice	Own provider

Description: Build APIs/connectors to automatically transfer transaction data to external electronic invoice systems (T-VAN providers) to issue invoices according to Decree 70/2025 regulations.

Implementation:

• Primary Integration: VNPAY Invoice - Leverage VNPAY ecosystem for seamless payment-to-invoice workflow
• Integrate with 2+ T-VAN providers (Primary: VNPAY Invoice, Backup: VNPT, MISA meInvoice)
• Auto-generate e-invoice on transaction complete
• Batch upload for offline transactions when back online
• Tax code lookup and validation
• Invoice cancellation and adjustment workflows
• Archive and retrieval for tax authority requirements

Invoice Management Features (Differentiator):

• Real-time Invoice Tracking - Instant visibility of invoice status in-app
• Unified Dashboard - Payment + Invoice status in single view
• Auto-Reconciliation - No manual matching between payment and invoice
• One-Click Adjustment - Single action updates both payment and invoice records
• Complete Audit Trail - Full transaction-to-invoice history in one place

Capability	Competitors	Our Solution
Payment-to-Invoice Flow	Separate systems, manual reconciliation	Unified automatic flow
Invoice Tracking	Delayed, via third-party T-VAN portal	Real-time, in-app visibility
Reconciliation	Manual matching required	Auto-matched, zero effort

VNPAY Invoice Advantage: Competitors integrate with external T-VAN providers (VNPT, Viettel, MISA meInvoice), creating disconnected workflows. Our VNPAY Invoice integration enables instant invoice generation, real-time tracking, and automatic reconciliation - all within a single platform.

4.9.2 Shipping Service Integration

Release: R3

Description: Connect with delivery partners (Logistics) to automatically create shipping orders, track delivery status.

Delivery Partner	Priority	Notes
GrabExpress	High	Most common
Giao Hàng Nhanh	High	Popular
Giao Hàng Tiết Kiệm	Medium	Budget option
Viettel Post	Medium	Wide coverage

4.9.3 Accounting Integration

Release: R2

Description: Connect with accounting systems for financial data export.

Accounting System	Priority
MISA	High
Fast Accounting	Medium
Generic export (Excel)	High

4.10 Financial Management

Release: R2

Competitor Reference: MISA leads with accounting integration

Description: Manage and record core financial data arising from sales, payments, and expenses.

• Revenue Recognition: Automatically record and classify revenue from completed sales transactions.
• Payment Reconciliation: Reconcile transaction data with reports from payment gateways (VNPAY) or banks.
• Accounting Data Management: Standardize and summarize financial entries for export to accounting systems.

4.11 BOM - Bill of Material

Release: R1 (MVP) | Priority: Must Have for F&B

Competitor Reference: CukCuk leads in F&B BOM

Feature	KiotViet	Haravan	CukCuk	MISA	Our Target
Create recipes/BOMs	❌	⚠️	✅	⚠️	✅
Ingredient list	❌	⚠️	✅	⚠️	✅
Yield/portion size	❌	⚠️	✅	⚠️	✅
Auto inventory deduction	❌	⚠️	✅	⚠️	✅
Cost calculation	❌	⚠️	✅	⚠️	✅
Single-level BOM	❌	⚠️	✅	⚠️	✅
Multi-level BOM	❌	❌	⚠️	⚠️	✅ (beat competitors)
Food cost % tracking	❌	❌	⚠️	⚠️	✅

Description: Manages the formula or list of components (raw materials, semi-finished products) required to manufacture or assemble a final product unit.

• Definition of BOM Structure: Create and maintain multi-level product formulas, specifying quantity and type of raw materials for each final product.
• Manufacturing Cost Calculation: Automatically aggregate costs of all components to determine COGS of the final product.
• Component Inventory Management: Calculate raw material requirements (MRP) based on BOM and order forecasts.

4.12 Table & Floor Management - NEW

Release: R1 (MVP) | Priority: Must Have for F&B

Competitor Reference: CukCuk ✅, iPOS ✅, KiotViet ⚠️, Haravan ❌

Feature	CukCuk	iPOS	KiotViet	Our Target
Visual floor plan	✅	✅	⚠️	✅
Drag-drop positioning	✅	⚠️	❌	✅
Table merge	✅	✅	❌	✅
Table split	✅	✅	❌	✅
Status indicators	✅	✅	⚠️	✅
Reservation integration	⚠️	✅	❌	✅ (beat CukCuk)
Default items on open	✅	⚠️	❌	✅
Multiple floors/areas	⚠️	✅	❌	✅

Description: Provides tools to set up and manage restaurant floor plans with visual table layouts, real-time status tracking, and table operations.

• Floor Plan Designer: Visual drag-drop interface to create and arrange table layouts by area/floor
• Table Status Management: Real-time status indicators (Available, Occupied, Reserved, Cleaning, Blocked)
• Table Operations: Merge tables for large groups, split tables for separate checks
• Order Linking: Associate orders with specific tables, transfer orders between tables
• Default Items: Auto-add items (water, service charge) when opening a table
• Capacity Management: Track covers, turnover time, and table utilization

4.13 Kitchen Display System - KDS - NEW

Release: R1 (MVP) | Priority: Must Have for F&B

Competitor Reference: CukCuk ✅, iPOS ✅, others ❌

Feature	CukCuk	iPOS	KiotViet	Our Target
Kitchen display	✅	✅	❌	✅
Order queue	✅	✅	❌	✅
Station routing	⚠️	⚠️	❌	✅ (improve)
Prep time tracking	⚠️	⚠️	❌	✅ (improve)
Order bumping	✅	✅	❌	✅
Priority flagging	✅	⚠️	❌	✅
Recall orders	✅	✅	❌	✅
Delta notifications	✅	✅	❌	✅
Color coding by age	⚠️	⚠️	❌	✅

Description: Digital display system for kitchen staff to view and manage incoming orders, improving kitchen efficiency and order accuracy.

• Order Queue Display: Show incoming orders in chronological order with item details
• Station Routing: Route items to appropriate stations (grill, bar, cold prep, etc.)
• Prep Time Tracking: Track time from order to completion, highlight delayed orders
• Order Bumping: Mark items/orders as complete, notify front-of-house
• Priority Orders: Visual flags for rush orders, VIP tables
• Recall Function: Bring back bumped orders if needed
• Color Coding: Green (new) → Yellow (aging) → Red (overdue)
• Kitchen Printer Integration: Print tickets as backup/supplement to display

4.14 QR Table Ordering - NEW

Release: R3 | Priority: Should Have

Competitor Reference: CukCuk ✅, iPOS ⚠️, others ❌

Feature	CukCuk	iPOS	Haravan	Our Target
QR code per table	✅	⚠️	⚠️	✅
Scan to view menu	✅	⚠️	⚠️	✅
Order from phone	✅	⚠️	⚠️	✅
Add to open order	✅	✅	❌	✅
Pay from phone	⚠️	⚠️	⚠️	✅
Call waiter	⚠️	⚠️	❌	✅ (improve)
Bill request	⚠️	⚠️	❌	✅ (improve)

Description: Enable customers to scan QR codes at their table to view menu, place orders, and request service without staff intervention.

• QR Generation: Unique QR code per table, regeneratable
• Digital Menu: Mobile-optimized menu with images, descriptions, prices
• Self-Ordering: Add items to order, customize (modifiers), submit to kitchen
• Open Order Addition: Add items to existing open order for the table
• Service Requests: Call waiter, request bill, ask for assistance
• Payment Option: Option to pay via QR (link to payment gateway)

5. Purchase System

Release: R1 (MVP) | Priority: Must Have

Implementation Status

Package: @nx/sale | Framework: IGNIS (Hono + Drizzle ORM)

• SaleOrder lifecycle: DRAFT → PROCESSING → COMPLETED / PARTIAL / CANCELLED
• CheckoutService with validation and revert capabilities
• PaymentWebhookService for VNPAY integration (success, failed, expired, cancelled)
• Real-time WebSocket events via Redis pub/sub → Signal service
• See Sale Service for technical details.

5.1 Cart Management

Description: Manages all activities related to the customer's shopping cart, ensuring a smooth shopping experience.

• Add/Delete/Update Products: Allow users to add products, adjust quantity, or delete items.
• Store Shopping Cart: Ensure cart is persistent across sessions and devices.
• Apply Preliminary Promotions: Calculate preliminary discounts and vouchers before checkout.

5.2 Order Management

Competitor Reference: All competitors have basic order management

Description: Manages the entire lifecycle of an order, from creation through processing to completion.

• Create and Update Orders: Convert cart to order, allow updates before confirmation.
• Manage Order Status: Track status lifecycle: DRAFT → PROCESSING (checkout) → COMPLETED (full payment) / PARTIAL (partial payment) / CANCELLED (manual, payment failed/expired/cancelled).
• Process Refunds and Cancellations: Handle cancellation and refund workflows.

Feature	KiotViet	CukCuk	iPOS	Our Target
Order creation	✅	✅	✅	✅
Status tracking	✅	✅	✅	✅
Order modification	✅	✅	✅	✅
Partial fulfillment	⚠️	✅	✅	✅
Refunds	✅	✅	✅	✅
Order notes	✅	✅	✅	✅
Split bill	⚠️	✅	✅	✅
Merge orders	❌	✅	✅	✅

5.3 Payment Management

Description: Coordinate payment processing for orders, interact with payment gateways (especially VNPAY).

• Transaction Initiation: Create payment requests and redirect to payment gateway.
• Payment Result Confirmation: Receive and process responses (callbacks) from payment gateway.
• Payment Method Management: Allow customers to select and store payment methods.

5.4 Transaction Management

Description: Manage all transactions arising from orders and payments in detail.

• Detailed Transaction Logging: Record all financial transactions with full details.
• Transaction Lookup and Reporting: Powerful search and reporting tools.
• Payment/Refund Status Tracking: Accurate status synchronization with order status.

5.5 Purchase Notifications

Release: R2

Note: Merged into unified Notification System (2.5).

6. Marketing System

Release: R3 | Priority: Should Have (Could Have for Free tier)

Partial Implementation

The Promotions Engine is now implemented in @nx/pricing (see Section 4.6.1), providing the foundation for voucher and discount functionality. Promotion types (Standard, Buy X Get Y) with fixed/percentage discount methods are operational. Full marketing campaign management, loyalty programs, and email campaigns remain planned for R3.

Competitor Reference: Haravan leads (80%), KiotViet (70%)

6.1 Voucher System

Feature	KiotViet	Haravan	CukCuk	Our Target
Fixed discount	✅	✅	✅	✅
Percentage discount	✅	✅	✅	✅
Free shipping	⚠️	✅	❌	✅
Buy X Get Y	✅	✅	⚠️	✅
Usage limits	✅	✅	⚠️	✅
Expiry dates	✅	✅	✅	✅
Product restrictions	✅	✅	⚠️	✅
Customer restrictions	⚠️	✅	⚠️	✅
Usage tracking	✅	✅	⚠️	✅

Description: Manage the entire lifecycle of voucher/coupon-based promotions.

• Create and Manage Vouchers: Set up different types (fixed, percentage, free shipping) with rules.
• Apply and Validate: Process code entries, check validity, calculate discounts.
• Track and Report: Reports on usage rate, effectiveness of campaigns.

6.2 Loyalty System

Competitor Reference: Haravan leads with tiered loyalty

Feature	KiotViet	Haravan	CukCuk	Our Target
Points earning	⚠️	✅	⚠️	✅
Points redemption	⚠️	✅	⚠️	✅
Membership tiers	❌	✅	⚠️	✅
Auto tier upgrade	❌	✅	❌	✅
Tier benefits	❌	✅	⚠️	✅
Birthday rewards	⚠️	✅	⚠️	✅
Points expiry	⚠️	✅	❌	✅

Description: Manage customer loyalty programs with points, tiers, and exclusive offers.

• Accumulate and Redeem Points: Set rules for earning and using points.
• Manage Membership Tiers: Define levels (Bronze, Silver, Gold) with auto-upgrade/downgrade.
• Exclusive Offers: Special offers for specific membership tiers.

6.3 Marketing Email

Release: R3

Note: Merged into unified Notification System (2.5) with campaign capabilities.

7. API Gateway

Release: R3 | Priority: Should Have (Enterprise focus)

Included: API GW - Internal Core System, API GW - WEB Channel, API GW - POS Channel

7.1 Load Balancer Gateway

Description: Responsible for efficiently distributing network traffic to different backend servers and services.

• Request Distribution: Use load balancing algorithms (Round Robin, Least Connections).
• Availability Assurance: Continuous health checks, automatic failover.
• High Traffic Handling: Handle sudden traffic spikes.
• Rate Limiting: Protect system from DDoS and resource abuse.
• Logging: Record all requests and responses for monitoring.

Note: For MVP/R1, use simple reverse proxy. Full API gateway deferred to R3 for scale requirements.

8. Admin Portal (BO)

Release: R2 | Priority: Should Have

Included: BO - Internal Core System, BO - WEB Channel, BO - POS Channel

Implementation Status

Two Back Office applications are now implemented:

• Back Office (Client) — @nx-app/client (port 3001) — General admin dashboard for managers/owners
• Back Office (Merchant) — @nx-app/bo (port 3000) — Merchant-facing B2B dashboard for store operations, customers, finance, purchase orders, and vendors

Both share @nx-app/core and @nx-app/ui-kit libraries. Stack: React 19 + Vite + Tailwind CSS + React Admin + Redux Toolkit. See Applications Overview and Back Office (Merchant) for technical details.

8.1 Dashboard

Description: Customizable home screen with real-time KPIs, charts, and quick-action widgets for business monitoring.

• KPI Cards: Revenue, orders, average ticket, top products - all updating in real-time
• Time Range Selector: View today, this week, this month, or custom date ranges
• Comparison Mode: Toggle to show % change vs previous period or same period last year
• Chart Widgets: Line charts for trends, bar charts for comparisons, pie charts for breakdowns
• Drag-Drop Layout: Arrange widgets to personalize dashboard per user preferences
• Multi-Location View: Aggregate all locations or drill down to specific store/terminal
• Alerts Panel: Surface low stock warnings, pending orders, and system notifications

8.2 User Management

Description: Full user administration including creation, profile editing, status control, and role assignment.

• User Directory: Searchable list with filters by role, status, and location assignment
• User Creation: Add new users with profile details; send activation email for password setup
• Bulk Import: Upload CSV to create multiple users at once for new store openings
• Status Actions: Activate, suspend, or permanently deactivate user accounts
• Role Assignment: Assign roles to users; support multiple roles per user
• Activity Log: View recent login history and actions performed by each user

8.3 Role Management

Description: Define and manage roles with granular permission bundles controlling access to features and data.

• Role Builder: Create custom roles by selecting permissions from categorized checklist
• Permission Preview: See exactly what each role can access before saving
• Role Cloning: Duplicate existing role as starting point for new variations
• User Count: See how many users are assigned to each role
• System Roles: View (but not edit) built-in roles like Owner and Admin
• Audit Trail: Track when roles are modified and by whom

8.4 Organization Management

Description: Manage merchant accounts, store locations, and organizational hierarchy.

• Merchant Profile: Business name, tax code, address, contact info, logo, and legal documents
• Store Locations: Add/edit physical locations with address, operating hours, and contact details
• Hierarchy View: Visualize organization structure (HQ → Regions → Stores)
• Subscription Status: View current plan, usage limits, and renewal dates
• Billing Info: Manage payment methods and view invoice history
• Data Export: Export all merchant data for backup or migration purposes

8.5 Device Management

Description: Monitor and control all POS terminals and devices across merchant locations.

• Device List: View all registered devices with status (online/offline), last seen, app version
• Device Details: Hardware info, assigned location, assigned users, activation date
• Remote Actions: Force sync, push config update, remote logout, or deactivate device
• Health Alerts: Notifications when device goes offline or app version is outdated
• Activation Codes: Generate new activation PINs for device pairing
• License Management: Track device count against subscription limits

8.6 Product Management

Description: Comprehensive product catalog management with variants, pricing, images, and sales channel assignment.

• Product List: Grid or table view with bulk actions (edit, duplicate, archive, delete)
• Product Editor: Full-featured form for name, description, SKU, barcode, images, and attributes
• Variant Management: Create size/color/flavor variants with individual SKUs and pricing
• Category Assignment: Assign products to one or multiple categories; drag to reorder
• Pricing Tab: Set base price, cost, compare-at price; assign to price lists
• Inventory Tab: View/adjust stock levels per location; set low-stock thresholds
• Channel Assignment: Control which products appear on POS, web store, or specific locations
• Bulk Operations: Import/export products via Excel; bulk price updates

8.7 Supply Management

Description: Purchase order management, vendor directory, and inventory receiving workflows.

• Vendor Directory: Manage supplier contacts, payment terms, and order history
• Purchase Orders: Create POs with line items, expected delivery dates, and approval workflow
• Receiving: Receive inventory against POs; handle partial receipts and discrepancies
• Cost Tracking: Record actual costs from POs; auto-update product cost averages
• Stock Transfers: Move inventory between locations with transfer orders
• Inventory Adjustments: Record stock corrections for damage, loss, or audit findings
• Reports: Stock movement history, PO status, vendor performance analytics

8.8 Sell-Order Management

Description: Order monitoring, fulfillment tracking, and customer service tools for handling issues.

• Order List: Filterable by status, date, channel, location, payment method, or customer
• Order Detail: View line items, payment info, customer details, and fulfillment status
• Status Updates: Change order status with optional customer notification
• Refunds: Process full or partial refunds with reason tracking
• Order Notes: Internal notes for staff communication; customer-visible notes
• Print/Reprint: Generate receipts, invoices, or packing slips
• Order Timeline: Audit trail showing all status changes and actions taken

8.9 Marketing Management

Release: R3

Description: Campaign creation, voucher management, and promotion scheduling for customer engagement.

• Voucher Builder: Create discount codes with rules (fixed amount, percentage, BOGO)
• Usage Controls: Set per-customer limits, total usage caps, and validity periods
• Product Targeting: Apply discounts to specific products, categories, or entire catalog
• Customer Targeting: Restrict vouchers to customer segments (new, VIP, birthday)
• Campaign Calendar: Visual timeline of all active and scheduled promotions
• Performance Tracking: Track redemption rates, revenue impact, and ROI per campaign

8.10 Customer Management

Implemented (Backend)

Customer CRUD is implemented in @nx/identity via the CustomerController with merchant-scoped access. The Back Office (Merchant) app provides the frontend screens. See Section 1.4 and Customer Management API.

Description: Customer database with purchase history, loyalty status, and communication tools.

• Customer Directory: Search by name, phone, email, or loyalty card number
• Customer Profile: Contact info, addresses, preferences, tags, and notes
• Purchase History: All orders with quick links to order details
• Loyalty Dashboard: Points balance, tier status, and redemption history
• Communication Log: Record of all emails, SMS, and support interactions
• Merge Duplicates: Combine duplicate customer records into single profile

8.11 Page Management

Release: R3

Description: Visual page builder for creating and customizing storefront pages without coding.

• Page Templates: Pre-built templates for home, product listing, about, contact pages
• Drag-Drop Editor: Add sections, rearrange blocks, customize styling
• Component Library: Banners, product grids, carousels, testimonials, CTAs
• SEO Settings: Edit page titles, meta descriptions, and URL slugs
• Preview Mode: View desktop and mobile previews before publishing
• Version History: Restore previous versions if needed

8.12 AI Assistant

Release: R4

Competitor Reference: MISA has voice ordering (2025); no competitor has analytics AI

Description: Conversational AI for natural language queries about business data, insights, and recommendations.

• Natural Language Queries: Ask questions like "What's my best-selling product this week?"
• Data Insights: AI surfaces trends, anomalies, and opportunities without being asked
• Report Generation: "Generate a sales report for last month" produces downloadable report
• Predictive Suggestions: "You usually run low on milk on Fridays - order more?"
• Voice Support: Optional voice input for hands-free queries (R4+)
• Context Awareness: AI understands current view and can answer questions about visible data

9. Client Portal

Release: R3 | Priority: Should Have

9.1 Home Page

Description: Engaging storefront homepage with promotions, featured products, and personalized recommendations.

• Hero Banners: Rotating promotional banners with links to campaigns or categories
• Featured Products: Curated product sections (new arrivals, bestsellers, on sale)
• Category Navigation: Visual category cards for quick browsing access
• Search Bar: Prominent search with autocomplete and recent searches
• Personalization: "Recommended for you" based on browsing and purchase history
• Quick Actions: Popular product quick-add buttons for repeat customers

9.2 Product Page

Description: Product catalog with rich filtering, sorting, and infinite scroll for seamless browsing.

• Product Grid: Responsive grid with thumbnail, name, price, and quick-add button
• Filters: Filter by category, price range, brand, availability, ratings
• Sort Options: Sort by relevance, price (low/high), newest, bestselling
• Infinite Scroll: Load more products automatically as user scrolls
• Quick View: Modal popup with product details without leaving the list
• Comparison: Select products to compare specifications side-by-side

9.3 Cart Page

Description: Shopping cart with item management, promo codes, and order summary before checkout.

• Cart Items: Product image, name, variant, quantity selector, line total
• Edit Quantity: Increase/decrease or remove items; update totals instantly
• Promo Codes: Enter discount codes with validation and applied discount display
• Order Summary: Subtotal, discounts, shipping estimate, taxes, and grand total
• Stock Warnings: Alert if item quantity exceeds available stock
• Saved Cart: Cart persists across sessions and devices for logged-in users

9.4 Checkout Page

Description: Streamlined checkout flow with delivery options, payment selection, and order confirmation.

• Guest or Login: Allow guest checkout or prompt login for faster future orders
• Delivery Address: Address form with validation; saved addresses for returning customers
• Delivery Options: Choose pickup, standard shipping, or express with estimated dates
• Payment Methods: Select from saved cards, VietQR, e-wallets, or cash on delivery
• Order Review: Final summary with itemized list and all fees before confirm
• Confirmation: Success page with order number, email confirmation, and tracking link

9.5 VNPAY Portal Payment

Description: Secure payment processing with VNPAY integration for QR codes, cards, and e-wallets.

• Payment Methods: VietQR, VNPAY QR, domestic/international cards, e-wallets
• Redirect Flow: Seamless redirect to VNPAY hosted payment page and back
• QR Display: Generate and display payment QR code for in-store or online payments
• Status Callback: Real-time payment status updates via webhook integration
• Retry Handling: Graceful handling of failed payments with retry options
• Receipt Generation: Auto-generate digital receipt upon successful payment

9.6 Customer Page

Description: Customer account area for profile management, order tracking, and loyalty information.

• Profile Settings: Edit name, email, phone, password, and notification preferences
• Address Book: Save multiple shipping/billing addresses for quick checkout
• Order History: List of past orders with status, tracking, and reorder option
• Order Detail: Full order breakdown with invoice download and return request
• Loyalty Dashboard: Points balance, tier status, available rewards, and history
• Wishlist: Save products to buy later; receive alerts when items go on sale

10. Artificial Intelligence Integration

Release: R4 | Priority: Could Have (Differentiator)

Competitor Reference: Only MISA has AI (voice ordering 2025); Gap for predictive analytics

10.1 Knowledge-based Management

Description: Curate and maintain the business knowledge base that powers AI responses and recommendations.

• Data Sources: Connect product catalog, order history, inventory, and customer data to AI
• Business Rules: Define pricing rules, return policies, and FAQs for AI to reference
• Training Data: Upload historical data for demand forecasting and pattern recognition
• Knowledge Updates: Real-time sync ensures AI always has current product and inventory info
• Custom Terminology: Teach AI business-specific terms, product nicknames, and abbreviations

10.2 Communication Mechanism

Description: Natural language interface for interacting with AI via text or voice across all touchpoints.

• Chat Interface: Text-based chat widget in Admin Portal and POS for quick queries
• Voice Input: Speech-to-text for hands-free interaction on POS terminals
• Multi-Language: Support for Vietnamese and English with automatic detection
• Context Retention: AI remembers conversation context for follow-up questions
• Suggested Actions: AI proposes clickable actions (view report, create order, adjust stock)
• Handoff to Human: Escalate complex issues to human support when AI cannot resolve

10.3 AI Authentication & Authorization

Description: Control what data and actions AI can access based on user permissions and safety guardrails.

• User Context: AI inherits permissions of the logged-in user making the request
• Data Scoping: AI only accesses data within user's permitted locations and merchants
• Read-Only Mode: By default, AI can query but not modify data without explicit confirmation
• Action Approval: Require user confirmation before AI executes write operations
• Audit Logging: All AI queries and actions logged with user attribution
• Rate Limits: Prevent excessive AI usage to control costs and ensure fair access

10.4 Predictive Analytics (NEW) - Future Differentiator

Competitor Reference: NO COMPETITOR has this - major opportunity

Description: AI-powered predictions and recommendations for business optimization.

• Sales Forecasting: Predict demand by product, day, time
• Inventory Optimization: Auto-suggest reorder quantities and timing
• Menu Engineering: Identify high-margin vs high-volume items (F&B)
• Staff Scheduling: Predict busy periods for optimal staffing
• Price Optimization: Dynamic pricing recommendations

Appendix A: Competitor Quick Reference

Competitor	Strength	Weakness	Our Opportunity
KiotViet	Large merchant base, affordable	Legacy UX, weak F&B	Better F&B + modern UX
Haravan	E-commerce, omnichannel	Complex, expensive, weak offline	Simpler + offline-first
CukCuk	F&B depth, KDS, table mgmt	Weak retail, no e-commerce	Dual vertical coverage
iPOS	Restaurant operations	Narrow focus	Broader F&B + retail
MISA	Accounting, compliance	Dated UX	Modern UX + compliance

Appendix B: Technology Stack

Layer	Technology	Details
POS App	Tauri + React 19	Rust-based desktop framework; barcode/QR scanning; printer integration; offline-capable
Admin Portal	React 19 + Vite 6	React Router 7, Redux Toolkit, TailwindCSS 4, React Admin
Backend Framework	IGNIS 0.0.7-7 (Hono 4.11.3)	DI container, base classes, JWT authentication, auth strategies
Runtime	Bun	TypeScript-native runtime; Bun.password (Argon2id) for hashing
Database	PostgreSQL + Drizzle ORM 0.45.1	Type-safe ORM with migrations; separate databases per microservice
Redis	Redis (5 instances/service)	Cache, BullMQ, pub/sub publisher, pub/sub subscriber, WebSocket emitter
Queue	BullMQ + Redis	Background job processing for payments, sync, commerce events
WebSocket	Signal Service + WebSocketEmitter	Redis pub/sub for real-time events; ECDH E2E encryption; room-based routing
Search	Typesense	Sub-50ms search; fuzzy matching; real-time indexing via Debezium CDC
Validation	Zod	Runtime type validation for API requests/responses
UI Components	shadcn/ui + Radix	Accessible, customizable component library
Shared Core	@nx/core	Database schemas, utilities, base classes shared across all backend services

Appendix C: Document History

Version	Date	Changes
0.1	Jan 2026	Initial proposal
1.0	Jan 2026	Added: Release roadmap, Freemium tiers, F&B features (Table, KDS, QR), Offline-first, Competitor references
1.1	Jan 2026	Added: VNPAY Invoice integration, PhonePOS (NFC) payment support, Tauri for Mobile POS, Typesense from MVP, Bun + Hono for backend
1.2	Feb 2026	Enhanced: Detailed technical descriptions for all modules reflecting actual implementation; Updated technology stack to match codebase
1.3	Feb 2026	Added: Implementation status annotations throughout; New Section 1.4 Customer Management (implemented in @nx/identity); Section 4.6.1 Promotions Engine (extracted to @nx/pricing); Sale service order lifecycle statuses; Back Office (Merchant) app reference in Section 8; Updated technology stack with IGNIS, Signal, Redis architecture; Cross-references to developer documentation