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.

🔒 Auth That Handles the Edge Cases You'll Eventually Hit

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).

Native OAuth pipelines are provided out of the box for:

  • Google
  • Apple

Plus 100+ additional providers (GitHub, Facebook, Twitter, etc.) that can easily plug-and-play natively via standard django-allauth configuration.

The system uses the X-Client-Id header to route OAuth requests to the correct application configuration automatically, supporting multiple mobile and web clients natively.

App Store Review Bypass

Passing App Store and Google Play reviews often requires providing a static login credential. The authentication system features a built-in, secure bypass (ENABLE_APP_STORE_TEST_ACCOUNT) that allows reviewers to instantly log in using a static OTP without requiring real email delivery, dramatically speeding up your time-to-market.

Deduplication & Disposable Email Blocking

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

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

☁️ Storage That Knows the Difference Between Public and Private

Managing large generative assets requires rock-solid storage and strict access control.

The boilerplate utilizes a Dual Storage Architecture via django-storages and MinIO/AWS S3: 1. PrivateMediaStorage: Requires pre-signed URLs to access. Files expire automatically after 5 hours. 2. PublicMediaStorage: Served directly via CDN with a 24-hour cache.

The SmartFileField

Instead of writing conditional logic to route files, you simply use our SmartFileField. This custom Django model field automatically inspects the instance's is_public property and routes the upload to the correct S3 bucket instantly.

# files/models.py
class File(BaseModel):
    file = SmartFileField(
        upload_to=UploadToPathAndRename("files"),
        max_length=500,
    )
    is_public = models.BooleanField(default=False)
(The UploadToPathAndRename class guarantees collision-proof, obfuscated filenames on upload.)

Feature-Based Upload Limits

The file upload architecture natively enforces distinct maximum file size limits based on the feature (e.g., Avatars vs. Generation Inputs) via the FEATURE_MAX_SIZES mapping, protecting your storage from excessively large unnecessary files.

🚩 Feature Flags That Actually Know Your Users

Feature flags shouldn't just be global ON/OFF switches.

Our feature flag engine uses PostgreSQL ArrayFields to implement powerful Targeting rules: - Platform targeting: Enable a feature only for iOS, or explicitly block Android users. - Localization targeting: Enable a feature only for users with fr or de locales. - Time windows: Automatically start and end a feature at specific UTC timestamps.

Blazing Fast Resolution

Mobile clients don't want to download 500 disabled flags. When a client calls /api/v1/feature-flags/active, the system uses the is_active_for() method to evaluate their specific device context, caches the tailored response in Redis for exactly 45 seconds, and returns only the flags they should see.

📢 System Messages & Translatability

The same targeting engine used for Feature Flags powers System Messages.

You can inject time-windowed announcements (e.g., "Server maintenance in 1 hour") or promotional banners directly into your mobile apps without a code deploy.

Because System Messages integrate with django-parler, you can translate the message title and body into all 10 supported languages directly from the Django Admin panel.

⚙️ Dynamic Configuration Store

Need to push a JSON configuration to your mobile app (like an updated color palette or a new ad network ID) but don't want to redeploy?

The CoreConstant model is a namespaced, database-backed key-value store. It uses Django Signals to instantly invalidate its Redis cache whenever you edit a value in the admin panel, guaranteeing clients receive the newest JSON instantly.

📱 Device Intelligence Middleware

The system automatically builds a deep understanding of your users' hardware without any frontend tracking code.

The UpdateUserClientContextMiddleware silently extracts the platform, language, locale, country, device model, device brand, and OS version from the incoming HTTP headers.

To protect the database from unnecessary writes, this extraction is guarded by a strictly enforced 24-hour write throttle per user.

This intelligence feeds into the UserDevice model, tracking hardware IDs, FCM push tokens, and per-device refresh tokens to give you complete visibility over a user's multi-device ecosystem.

Error Handling & Responses

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

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.

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.