Core - Foundation Architecture

Domain: Core Infrastructure Location: api/nextango/apps/core/ Last Updated: 2026-07-09

Overview

The Core app provides the foundational architecture the rest of the platform builds on: the model inheritance spine (UUID primary keys, timestamps, Sanity CMS sync with revision tracking and deletion semantics), validators for input sanitization and business rules, the EncryptedJSONField custom field, caching and performance utilities, centralized secure error handling, shared admin infrastructure (editorial widgets, sync-health indicators, deletion guards), pagination defaults, and the database replica router.

Documentation Quick Links

The Model Inheritance Spine

Every domain model inherits from one of three abstract bases defined in core/models/base.py:

• BaseModel provides a UUID primary key (models/base.py:63-70).
• TimestampedModel extends BaseModel with created_at / updated_at (models/base.py:73-81).
• SanityIntegratedModel extends TimestampedModel with bidirectional Sanity CMS sync: sanity_id / sanity_rev, sync status tracking, deterministic revision-based sync decisions (django_revision vs last_synced_django_revision), and the origin-aware safe_delete() deletion contract (models/base.py:84-577).

Two mixins in core/models.py compose with these: AuditableMixin (created_by / updated_by Employee FKs) and SoftDeleteMixin (is_deleted / deleted_at / deleted_by fields).

The choice of base class is an ownership statement. A record authored in Sanity Studio is Sanity-owned and inherits SanityIntegratedModel with sync on; a record born from a transaction or operational event is Django-owned and either uses a plain base or sets _outbound_sync_enabled = False. Full details on the sync lifecycle and deletion semantics: models.md.

Key Components

Validators

core/validators.py provides InputSanitizer (text, identifier, and email sanitization with XSS and SQL-injection pattern checks), FinancialValidator (Decimal amount validation with per-domain limits), BusinessRuleValidator (store hours, employee permissions, transaction-state integrity), and InventoryValidator (quantity and store-scoped availability checks). See validators.md.

EncryptedJSONField

core/fields.py defines EncryptedJSONField, a TextField subclass that stores a dict Fernet-encrypted at rest and decrypts transparently on read. Used for payment processor credentials and similar secrets. See fields.md.

Caching

core/utils/cache.py provides cache_result (function-result caching), make_cache_key_func (DRF response caching key functions), and invalidate_cache_pattern (SCAN-based prefix invalidation wired to model signals across domains). See caching.md.

Secure Error Handling

core/exceptions.py defines the exception classes (SecurityException, PaymentSecurityException, BusinessLogicException, TransactionException, InventoryException), the SecureError client-safe response shape, the DRF secure_exception_handler, the @handle_view_exception decorator, and ErrorReportingMiddleware (per-request request_id, X-Request-ID response header). See exceptions.md.

Shared Admin Infrastructure

core/admin/ exports the editorial widgets that render Sanity reference JSON as labeled dropdowns and checklists (SanityRefField, SanityRefArrayField, SanityOptionsField, SanityStringChecklistField, SanityTagListField), the SanityObjectFormMixin for nested-object JSONFields, read-only JSON display helpers, the sync-health admin mixins, and the SanityDeletionGuardAdminMixin that enforces deletion semantics in the admin. Used by the users, products, stores, promotions, and procurement admins. See admin.md.

Pagination

core/pagination.py defines StandardResultsSetPagination, the platform-wide DRF default: page size 20, client-overridable via ?page_size= up to 1000.

Database Replica Router

core/db_router.py defines ReplicaRouter: reads route to the replica database when configured and enabled (USE_REPLICA_DATABASE), writes always go to default, reads inside transactions stay on default for consistency, and migrations run only on default.

Endpoints

Core registers two HTTP surfaces in the root URLconf (api/nextango/urls.py):

Dashboard overview

GET /dashboard/overview/ (nextango/urls.py:139, core/views/dashboard_overview.py) returns headline KPIs aggregated across the transactions, products, users, and integrations analytics services in one response. Accepts ?store_id=, ?start_date=, ?end_date=. Requires an authenticated web session (WebSessionAuthentication + IsAuthenticated). Each KPI block is independent: a failing service logs a warning and returns null for that block instead of failing the request. The result is cached for 300 seconds per (store, date-range) combination.

Health check

GET /health/ (nextango/urls.py:180, django-health-check) reports database, cache, and file-storage checks. HTML by default; ?format=json returns:

{
  "DatabaseBackend": "working",
  "CacheBackend": "working",
  "DefaultFileStorageHealthCheck": "working"
}

All checks passing returns HTTP 200; any failing check returns HTTP 500. Nginx proxies this endpoint for load balancer and uptime monitor use.

Related Domains

All business domains inherit from Core:

• Users uses the base models, validators, and admin widgets
• Products uses the base models and caching
• Transactions uses FinancialValidator and the exception classes
• Stores uses SanityIntegratedModel and response caching
• Integrations drives the sync lifecycle the base models track

Next Steps

1. Start with models.md for the inheritance spine and deletion semantics
2. Then validators.md for validation patterns
3. Review caching.md for the response-cache architecture
4. Check admin.md for the editorial admin widgets
5. Study examples.md for working code