bakery-ia/services/pos/README.md

POS Integration Service

This service handles integration with external Point of Sale (POS) systems for the Bakery IA platform.

Supported POS Systems

• Square POS - Popular payment and POS solution with strong API support
• Toast POS - Restaurant-focused POS system with comprehensive features
• Lightspeed Restaurant - Full-featured restaurant management system

Features

• Real-time webhook handling from POS systems
• Bidirectional data synchronization with sales service
• Secure credential management with encryption
• Multi-tenant support with tenant-specific configurations
• Comprehensive transaction logging and audit trails
• Automatic duplicate detection and handling
• Rate limiting and retry mechanisms for reliability

Architecture

The POS service follows the established microservices architecture:

POS Service
├── API Layer (FastAPI)
├── Business Logic (Services)
├── Data Access (Repositories)
├── External Integrations (POS Providers)
├── Webhook Handlers
└── Background Sync Jobs

API Endpoints

Configuration Management

• GET /api/v1/tenants/{tenant_id}/pos/configurations - List POS configurations
• POST /api/v1/tenants/{tenant_id}/pos/configurations - Create new configuration
• PUT /api/v1/tenants/{tenant_id}/pos/configurations/{config_id} - Update configuration
• DELETE /api/v1/tenants/{tenant_id}/pos/configurations/{config_id} - Delete configuration

Webhook Handling

• POST /api/v1/webhooks/{pos_system} - Receive webhooks from POS systems
• GET /api/v1/webhooks/{pos_system}/status - Get webhook status

Data Synchronization

• POST /api/v1/tenants/{tenant_id}/pos/configurations/{config_id}/sync - Trigger sync
• GET /api/v1/tenants/{tenant_id}/pos/configurations/{config_id}/sync/status - Get sync status
• GET /api/v1/tenants/{tenant_id}/pos/transactions - Get POS transactions

Database Schema

Core Tables

• pos_configurations - POS system configurations per tenant
• pos_transactions - Transaction data from POS systems
• pos_transaction_items - Individual items within transactions
• pos_webhook_logs - Webhook event logs
• pos_sync_logs - Synchronization operation logs

Environment Variables

See app/core/config.py for all configuration options. Key variables include:

# Database
POS_DATABASE_URL=postgresql+asyncpg://pos_user:pos_pass123@pos-db:5432/pos_db

# POS Provider Credentials
SQUARE_APPLICATION_ID=your_square_app_id
SQUARE_ACCESS_TOKEN=your_square_token
TOAST_CLIENT_ID=your_toast_client_id
LIGHTSPEED_CLIENT_ID=your_lightspeed_client_id

# Webhook Configuration
WEBHOOK_BASE_URL=https://your-domain.com
WEBHOOK_SECRET=your_webhook_secret

Development

Running the Service

# Using Docker Compose (recommended)
docker-compose up pos-service

# Local development
cd services/pos
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Database Migrations

# Create migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

Testing

# Run tests
pytest tests/

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

Security Considerations

• POS credentials are encrypted before storage
• Webhook signatures are verified for authenticity
• All API endpoints require tenant-based authentication
• Rate limiting prevents abuse
• Sensitive data is logged with appropriate redaction

Monitoring

The service includes comprehensive monitoring:

• Health check endpoints
• Prometheus metrics
• Structured logging
• Performance tracking
• Error rate monitoring

Integration Flow

1. Configuration: Set up POS system credentials via API
2. Webhook Registration: Register webhook URLs with POS providers
3. Real-time Events: Receive and process webhook events
4. Data Sync: Periodic synchronization of transaction data
5. Sales Integration: Forward processed data to sales service