POS Gateway - Real-Time Terminal Integration

Domain: POS Gateway Location: api/nextango/apps/pos_gateway/ Last Updated: 2026-07-09

Overview

Renamed: This app was formerly pos_realtime. It was refactored and renamed to pos_gateway to reflect its expanded scope beyond real-time messaging. The deprecated pos_realtime app is fully removed; only pos_gateway is active.

The POS Gateway app provides real-time integration with POS terminals through JWT-based authentication, WebSocket connections for live updates, manager approval workflows, terminal session management, cash drawer integration, and broadcast/messaging infrastructure for hardware. Designed for high-performance retail operations.

Documentation Quick Links

Core Documentation

Key Features

JWT-based terminal sessions. Terminals authenticate with an employee PIN and receive an 8-hour JWT session, tracked in a TerminalSession row and validated on every request via Redis-first, database-fallback lookup. See Authentication.

WebSocket real-time connections. TerminalConsumer and ManagerConsumer provide bidirectional real-time updates over Redis-backed channel groups: terminal-specific, store-wide, and manager-dashboard groups. See Consumers and Broadcast Utilities.

Manager approval workflows. A terminal can request manager sign-off for a discount, void, return, price override, cash drawer access, or refund. The request is created via REST or WebSocket, notified to managers over WebSocket, and decided by a manager on their own dashboard connection. See Consumers and Services.

Cash drawer trigger. The gateway exposes a hardware-level drawer-open trigger for the terminal. Full register lifecycle (close with variance, till count) is handled by CashDrawerViewSet in the transactions app, not here.

Startup cache warming. On app startup, GatewayInitializationService pre-warms Redis with active product variants and store configuration so the first POS request after a deploy doesn't pay a cold-cache database lookup. See Services.

Note: SKU and barcode lookup, and inventory reservation, were previously handled by dedicated gateway endpoints and services. Both were removed during the gateway refactor. The POS frontend calls the products API directly, and inventory holds are managed by the transactions app's own reservation logic. See the note under API Endpoints below.

API Endpoints

Terminal Authentication

Transaction Operations

Manager Approvals

Cash Drawer

Health & Audit

WebSocket Channels

Note: POS inventory lookup is handled directly by the products API: GET /product-variants/?sku=<barcode>. The dedicated pos_gateway inventory endpoints (inventory/lookup/ and inventory/reserve/) were removed during the gateway refactor. The POS frontend calls the products ViewSet directly.

Full endpoint documentation: views.md

Architecture Highlights

WebSocket Channels

Real-time bidirectional communication:

Terminal Channel: /ws/pos-gateway/terminal/{terminal_id}/
  - Transaction updates
  - Inventory notifications
  - Approval responses
  - Heartbeat messages

Manager Channel: /ws/pos-gateway/manager/{store_id}/
  - Approval requests
  - Store-wide notifications
  - Dashboard updates
  - Alert broadcasts

Read more: consumers.md, broadcast.md

JWT Authentication Flow

Secure terminal authentication:

1. Terminal login with employee PIN
2. JWT token issued with terminal session (8-hour expiration)
3. Token used for API and WebSocket auth
4. Session tracking and heartbeat via Redis-first, database-fallback validation

There is no token refresh endpoint; a terminal re-authenticates with the PIN when its session expires.

Read more: authentication.md

Redis-Powered Performance

Caching and channel-layer pub/sub:

• Product and store lookup cache, warmed on app startup
• Session state cache for fast JWT revalidation
• WebSocket message pub/sub via channels_redis.pubsub.RedisPubSubChannelLayer

Read more: infrastructure.md

Service Layer Architecture

Gateway logic centralized in service classes, each a thin orchestration layer over domain services:

• GatewayInitializationService - Startup cache warming
• TransactionGatewayService - Transaction creation and payment, delegating to TransactionService and PaymentService
• ManagerApprovalGatewayService - Approval request creation and status
• CashDrawerGatewayService - Cash drawer open trigger
• WebSocketBroadcaster (utils/broadcast.py) - WebSocket message distribution

Read more: services.md

Getting Started

1. Understand the Models

Start with models.md to understand:

• TerminalSession (terminal_id, user, auth_token, last_heartbeat)
• ManagerApprovalRequest (request_type, terminal_session, requested_by, approved_by, status)
• InventoryReservation and GatewayPerformanceMetric are defined but currently have no writer anywhere in the codebase

2. Review Authentication

Read authentication.md to understand:

• JWT token generation and validation
• Terminal login workflow
• Session management
• Token refresh mechanism

3. Explore WebSocket Consumers

Check consumers.md to learn:

• Terminal WebSocket consumer
• Manager WebSocket consumer
• Message handling
• Connection lifecycle

4. Study Service Layer

Review services.md for:

• Transaction creation and payment orchestration
• Manager approval workflows
• Cash drawer trigger
• Startup cache warming

Related Domains

• Users - Employee authentication and PIN validation
• Stores - Store and terminal configuration
• Transactions - POS transaction processing
• Products - Product and inventory lookup
• Payments - Payment processing integration

Key Architectural Decisions

1. JWT authentication - Stateless-looking terminal sessions backed by a database row, so revocation is possible despite the JWT itself being stateless
2. WebSocket real-time - Instant updates, no polling required
3. Redis caching - Fast product/store lookup and session revalidation
4. Delegation over duplication - Gateway services orchestrate transactions, payments, and products domain services rather than reimplementing business logic
5. Manager approvals - Real-time approval workflow over WebSocket
6. Heartbeat monitoring - Detect stale terminal sessions
7. Service layer - Business logic centralized in gateway services, testable independent of views

Common Use Cases

• Terminal login - Employee PIN authentication, JWT session creation
• Transaction processing - Create a transaction, then apply payment
• Manager approval - Request and process discount, void, return, or price override approvals
• Cash drawer - Trigger the physical drawer open
• Real-time updates - WebSocket notifications for transactions and approvals
• Terminal monitoring - Heartbeat-driven session activity tracking
• Audit logging - Client-emitted audit events for security and compliance review

Service Methods

GatewayInitializationService

• initialize() - Run cache warming on app startup
• _warm_product_cache() - Cache active product variants by SKU and Sanity ID
• _warm_store_cache() - Cache store configuration by Sanity ID and database ID

TransactionGatewayService

• create_transaction(terminal_session, transaction_data) - Create a sale transaction via TransactionService
• process_payment(terminal_session, transaction_id, payment_data) - Apply payment via PaymentService, committing reserved inventory when the transaction completes

ManagerApprovalGatewayService

• request_approval(terminal_session, request_type, amount, reason, details) - Create a ManagerApprovalRequest
• check_approval_status(request_id) - Poll approval status (fallback path; the primary notification is via WebSocket)

CashDrawerGatewayService

• open_drawer(terminal_session, reason) - Trigger the physical drawer open via CashDrawerService

WebSocketBroadcaster (utils/broadcast.py)

• broadcast_transaction_created(transaction, store_id)
• broadcast_transaction_updated(transaction, store_id, updates)
• broadcast_transaction_completed(transaction, store_id, payment_method)
• broadcast_return_processed(return_record, store_id)
• broadcast_inventory_update(variant_sku, store_id, available_quantity, reserved_quantity)
• broadcast_system_notification(store_id, message, severity)

Full documentation: services.md

Next Steps

1. Start with models.md - Understand the data structure
2. Then authentication.md - Learn JWT authentication
3. Review consumers.md - Explore WebSocket connections
4. Study services.md - Learn business logic
5. Check broadcast.md - Understand real-time messaging
6. Review infrastructure.md - See Redis and WebSocket setup
7. Explore views.md - See API endpoints