Skip to content

Core Concepts

This section covers the fundamental concepts that power the Apptork Root System. From handling secure, passwordless authentication to ensuring the absolute integrity of your database.

Authentication & Users

The Root System provides frictionless, multi-provider authentication. We explicitly avoid exposing Django's default template-based auth (e.g., password reset pages) to prioritize headless, client-driven flows.

By default, the system utilizes Email One-Time Passwords (OTP). Users request an OTP, and the system issues a temporary token. Upon verifying the OTP, the system exchanges it for an enterprise-grade JSON Web Token (JWT).

Through dj-rest-auth and allauth, native OAuth pipelines are provided out of the box for:

  • Google
  • Apple
  • GitHub

Seamless Merging

The identity management system handles merging accounts naturally when a user signs in with a previously verified email address via a different provider.

Fraud Prevention & Security

Root System is engineered to protect valuable AI resources from bad actors.

Deduplication Engine

Accounts are strictly deduplicated. When a new user registers, the system assesses their IP Address, physical Device ID, and normalized email alias (e.g., user+spam@gmail.com -> user@gmail.com) to prevent promotional abuse.

Disposable Email Blocking

To further protect against abuse and bot registrations, the system actively cross-references incoming registrations against a comprehensive blacklist of disposable and temporary email providers (e.g., Mailinator, TempMail). Attempts to register with these domains are automatically rejected.

API Rate Limiting & Throttling

A granular throttling engine protects endpoints. Distinct limits are enforced based on the endpoint's nature and the user's role:

  • Anonymous Rates: Extremely restricted (e.g., OTP requests).
  • Authenticated Rates: Standard operational limits.
  • AI Generation Rates: Aggressive throttling to prevent token drain and wallet depletion.
  • Checkout Rates: Heavily protected against carding attacks.

Error Handling & Responses

Say goodbye to unpredictable HTTP 500s throwing HTML into your mobile app.

Standardized Payloads

The entire API uses drf-standardized-errors. All error responses are universally predictable, typed, and easily parsed.

Example Error Response
{
  "type": "client_error",
  "errors": [
    {
      "code": "invalid_credit",
      "detail": "Insufficient balance for this operation.",
      "attr": "credits"
    }
  ]
}

Why this matters

This guarantees your clients can build robust UI around specific error keys without relying on volatile string-matching.

File Management & S3 (MinIO)

Managing large generative assets requires rock-solid storage.

The boilerplate utilizes django-storages paired with a containerized MinIO instance during local development. MinIO perfectly emulates the AWS S3 API.

Transitioning to Production

When transitioning to production, you merely update the .env.prod environment variables (e.g., AWS_ACCESS_KEY_ID), and the application routes assets seamlessly to S3. No codebase changes required.

Health Checks & System Observability

Keeping tabs on a distributed application requires robust tooling.

Modular Health Probes

A dedicated layer powered by django-health-check ensures instant visibility into your infrastructure. Visiting the obfuscated health URL performs live tests on:

  • PostgreSQL Read/Write capability
  • Redis connection integrity
  • :material-worker: Celery Worker responsiveness
  • S3/MinIO bucket access
  • Raw memory and disk usage

Sentry SDK for Async Tracking

Sentry is pre-wired explicitly for Django and Celery. Exceptions caught during an asynchronous background task retain their full stack trace, contextual variables, and user context.

Feature Flags & System Messages

Real-Time Toggling

The core application includes an ActiveFeatureFlagsView. You can flip database flags to instantly disable features globally without redeploying code.

Over-The-Air (OTA) Messages

A remote payload injection architecture allows operators to broadcast localized alerts directly to the clients. Instead of raw JSON payloads, the system utilizes django-parler, ensuring perfect and robust translatability for dynamic fields directly at the database level.

Localization (i18n) Engine

The backend natively supports global scale.

  • Dynamic Content: We use django-parler for translating database models (e.g., OTA messages, dynamic configuration). Mobile and frontend clients simply send the Accept-Language HTTP header, and the API seamlessly returns the correct translation values.
  • Static API Content: Utilizing Django's standard translation framework alongside .po and .mo files, the API surfaces static error messages, validation faults, and operational alerts automatically based on the Accept-Language HTTP header.
  • Client-Side Translations: Please note that frontend and mobile clients handle their own translation mechanisms for their non-dynamic content (e.g., hardcoded button texts, UI labels, menus).

The Admin Control Plane

The centralized Django Administration panel has been meticulously customized. It acts as the Operator Arsenal—a command center to manually adjust wallet balances, review transaction ledgers, investigate failed tasks, and trigger refunds, all through a secure visual interface.