README.md

metadata

title: Cuatro Labs POS
emoji: 🛒
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
short_description: Point of Sale System - Sales & Inventory Management

Point of Sale (POS) Microservice

A comprehensive FastAPI-based microservice for managing point of sale operations, inventory management, and customer transactions within the Insightfy Bloom platform. This service provides robust APIs for sales processing, inventory tracking, customer management, and transaction handling.

Features

Sales Management

• Real-time sales transaction processing
• Multiple payment method support (Cash, Card, Digital Wallets)
• Receipt generation and printing
• Sales analytics and reporting
• Discount and promotion management
• Tax calculation and GST integration

Inventory Management

• Real-time stock tracking
• Low stock alerts and notifications
• Barcode scanning and product lookup
• Batch and serial number tracking
• Stock adjustments and corrections
• Inventory valuation (FIFO, LIFO, Weighted Average)

Customer Management

• Customer registration and profiles
• Loyalty program integration
• Purchase history tracking
• Customer analytics and insights
• Targeted promotions and offers

Product Catalog

• Product master data management
• Category and brand organization
• Pricing and variant management
• Product images and descriptions
• Bulk import/export capabilities

Reporting & Analytics

• Daily sales reports
• Inventory turnover analysis
• Customer behavior analytics
• Top-selling products insights
• Profit margin analysis
• Tax reporting

Authentication & Security

• JWT-based authentication
• Role-based access control (Cashier, Manager, Admin)
• Secure payment processing
• Audit trails for all transactions
• PCI DSS compliance support

Architecture

Technology Stack

• Framework: FastAPI 0.104.1
• Database: MongoDB (via Motor async driver)
• Cache: Redis
• Authentication: JWT (python-jose)
• Payment Processing: Stripe/PayPal integration
• Server: Uvicorn with async support

Project Structure

app/
├── routers/          # API route handlers
│   ├── sales_router.py
│   ├── inventory_router.py
│   ├── customer_router.py
│   ├── product_router.py
│   ├── payment_router.py
│   └── report_router.py
├── services/         # Business logic layer
│   ├── sales_service.py
│   ├── inventory_service.py
│   ├── customer_service.py
│   ├── product_service.py
│   ├── payment_service.py
│   └── report_service.py
├── models/           # Database models
├── schemas/          # Pydantic validation schemas
│   ├── sales_schema.py
│   ├── inventory_schema.py
│   ├── customer_schema.py
│   ├── product_schema.py
│   └── payment_schema.py
├── constants/        # Application constants
│   ├── collections.py
│   ├── payment_types.py
│   ├── product_categories.py
│   ├── transaction_types.py
│   └── validation.py
├── core/             # Core configuration
│   ├── config.py
│   └── logging_config.py
├── utils/            # Utility functions
├── dependencies/     # FastAPI dependencies
├── main.py           # Application entry point
├── nosql.py          # MongoDB connection
└── cache.py          # Redis cache management

API Endpoints

Health Check

• GET /health - Service health status

Sales Endpoints (/api/v1/sales)

• POST /api/v1/sales/transaction - Process new sale
• GET /api/v1/sales/transaction/{transaction_id} - Get transaction details
• POST /api/v1/sales/receipt - Generate receipt
• GET /api/v1/sales/daily-summary - Get daily sales summary
• POST /api/v1/sales/return - Process return/refund
• GET /api/v1/sales/history - Get sales history

Inventory Endpoints (/api/v1/inventory)

• POST /api/v1/inventory/stock - Add stock
• GET /api/v1/inventory/stock/{product_id} - Get current stock
• PUT /api/v1/inventory/stock/{product_id} - Update stock levels
• POST /api/v1/inventory/adjustment - Stock adjustment
• GET /api/v1/inventory/low-stock - Get low stock alerts
• GET /api/v1/inventory/valuation - Get inventory valuation

Product Endpoints (/api/v1/products)

• POST /api/v1/products - Create new product
• GET /api/v1/products/{product_id} - Get product details
• PUT /api/v1/products/{product_id} - Update product
• DELETE /api/v1/products/{product_id} - Delete product
• GET /api/v1/products - List products with filters
• GET /api/v1/products/barcode/{barcode} - Get product by barcode

Customer Endpoints (/api/v1/customers)

• POST /api/v1/customers - Register new customer
• GET /api/v1/customers/{customer_id} - Get customer profile
• PUT /api/v1/customers/{customer_id} - Update customer
• GET /api/v1/customers/{customer_id}/history - Get purchase history
• POST /api/v1/customers/{customer_id}/loyalty - Update loyalty points
• GET /api/v1/customers/search - Search customers

Payment Endpoints (/api/v1/payments)

• POST /api/v1/payments/process - Process payment
• GET /api/v1/payments/{payment_id} - Get payment status
• POST /api/v1/payments/refund - Process refund
• GET /api/v1/payments/methods - Get available payment methods

Report Endpoints (/api/v1/reports)

• GET /api/v1/reports/daily-sales - Daily sales report
• GET /api/v1/reports/inventory-turnover - Inventory turnover report
• GET /api/v1/reports/top-products - Top selling products
• GET /api/v1/reports/customer-analytics - Customer analytics
• GET /api/v1/reports/tax-summary - Tax summary report

Environment Configuration

Copy .env.example to .env and configure:

# Application
APP_NAME=POS Microservice
APP_VERSION=1.0.0
DEBUG=false

# MongoDB
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=pos_db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# JWT Authentication
SECRET_KEY=your-secret-key-change-in-production
ALGORITHM=HS256
TOKEN_EXPIRATION_HOURS=8

# Payment Gateway
STRIPE_SECRET_KEY=sk_test_your_stripe_key
STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_key
PAYPAL_CLIENT_ID=your_paypal_client_id
PAYPAL_CLIENT_SECRET=your_paypal_secret

# Tax Configuration
GST_RATE=18.0
TAX_CALCULATION_MODE=inclusive

# Receipt Configuration
RECEIPT_HEADER=Your Store Name
RECEIPT_FOOTER=Thank you for your business!
RECEIPT_PRINTER_TYPE=thermal

# Logging
LOG_LEVEL=INFO

Getting Started

Prerequisites

• Python 3.11+
• MongoDB
• Redis
• Payment gateway accounts (Stripe/PayPal)

Local Development

1. Clone the repository and navigate to the project directory

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure environment variables:

cp .env.example .env
# Edit .env with your configuration

5. Run the service:

uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

6. Access the API documentation:

• Swagger UI: http://localhost:8001/docs
• ReDoc: http://localhost:8001/redoc

Docker Deployment

Build and run with Docker:

# Build the image
docker build -t pos-microservice .

# Run the container
docker run -p 7861:7861 --env-file .env pos-microservice

The service will be available at http://localhost:7861

Testing

Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=app tests/

# Run specific test file
pytest tests/test_sales_schemas.py

Examples

Check the examples/ directory for usage examples:

• quick_start.py - Basic API usage
• sales_transaction_example.py - Sales transaction workflow

API Documentation

Once the service is running, interactive API documentation is available at:

• Swagger UI: /docs
• ReDoc: /redoc

Contributing

This service follows standard FastAPI best practices:

• Async/await for all I/O operations
• Pydantic models for request/response validation
• Dependency injection for shared resources
• Structured logging with python-json-logger
• Property-based testing with Hypothesis

License

Part of the Insightfy Bloom platform by Cuatro Labs.

Support

For issues and questions, please refer to the project documentation or contact the development team.