Stores Domain - Services Documentation

Source: api/nextango/apps/stores/services.py Last Updated: 2026-07-09

Overview

Two service classes: StoreService computes the store summary served by the retrieve endpoint, and DashboardService aggregates the dashboard home payload.

StoreService

Purpose: Store-level aggregated metrics.

Source: services.py:7-74

get_store_summary(store_id)

Returns a summary dict for one store. Cached for 300 seconds per store_id. Raises Store.DoesNotExist for an unknown id (the view maps this to 404).

Parameters: store_id (the store's Django UUID). Call with the keyword form get_store_summary(store_id=...) so the per-store cache keying applies.

Reads run against the replica database when USE_REPLICA_DATABASE is enabled, otherwise against the default database.

Response shape:

{
    'id': UUID,
    'sanity_id': 'store-...',
    'store_code': 'COL001',
    'name': 'Columbus Main Street',
    'is_active': True,
    'is_default': False,
    'timezone': 'America/New_York',
    'employee_count': 25,
    'active_zones_count': 8,
    'total_zones_count': 10,
    'recent_compliance_checks_count': 12,
}

Computed metrics:

  • employee_count: employees whose store_assignments JSON contains this store, matched three ways to tolerate the stored shapes: the store's Django UUID string, its sanity_id, or a {'_ref': sanity_id} reference object.
  • active_zones_count: the store's zones with is_shown=True.
  • total_zones_count: all zones of the store.
  • recent_compliance_checks_count: compliance checks across the store's zones in the last 30 days, computed in a single aggregate query.

This summary is the response body of GET /stores/{store_code}/; see Views.

DashboardService

Purpose: One-call aggregation for the dashboard home screen.

Source: services.py:77-168

get_dashboard_home(store_id)

Returns the dashboard home payload for one store. Cached for 60 seconds per store_id. Raises Store.DoesNotExist for an unknown id.

Sections:

  • kpis: revenue_today (sum of totalAmount over today's completed transactions, UTC date; TIME_ZONE is UTC and no per-store timezone is activated), transactions_today (count), avg_transaction_value (revenue divided by count, "0.00" with no transactions), and active_promotions (count of active PromotionalCampaign records; intentionally global, since campaigns carry no relational store FK).
  • top_products_today: up to 5 products ranked by revenue for today, delegated to the products analytics service.
  • low_stock_alerts: up to 10 active InventoryLevel rows where stock_on_hand <= reorder_point and reorder_point > 0, each with variant_sku, name, stock_on_hand, reorder_point.
  • recent_transactions: the 10 most recent transactions for the store, any status, each with transaction_id, total, status, timestamp.

Full response schema with field tables: Dashboard Home.

Was this page helpful?