Introduction

Welcome to the Apptork Root System documentation!

This is the ultimate, production-ready Django + Celery backend boilerplate explicitly designed for scaling autonomous AI assets and SaaS applications. Root System provides a rigorous foundation built on high-performance infrastructure, strict security protocols, and modular AI expansion.

🚀 Quickstart Guide 🏗️ What's Inside ⚙️ Core Concepts

Overview

The Apptork Root System is an enterprise-grade foundational platform designed to accelerate the deployment and scaling of complex applications. Built with Django 5.2, PostgreSQL, and Redis, it provides a highly resilient architecture featuring:

Omni-Domain AI Orchestration: A unified, polymorphic framework powered by Celery and Redis that handles heavy inference loads, dynamic DAG workflows, automated prompt translation via langdetect, and strict prompt-leak protection.
Enterprise-Grade DevOps & Parity: Fully containerized setup ensuring absolute parity from local development (via MinIO) to production (AWS S3) using SmartFileField auto-routing, backed by zero-downtime health probes and ASGI concurrency.
Turnkey Monetization & Ledgers: Native cross-platform synchronization with RevenueCat and Lemon Squeezy, operating on an immutable transactional wallet with geospatial promotional logic and anomaly detection.
Omnichannel Auth & Fraud Prevention: Frictionless passwordless flows (OTP) and native OAuth, fortified by strict deduplication, disposable email blocking, device intelligence fingerprinting, and specialized App Store review bypass mechanisms.
Real-Time Data & Global Scale: Natively integrated Server-Sent Events (SSE) with ownership-based channel authorization, out-of-the-box internationalization (i18n) for 10 languages, and real-time database-backed feature flags.

To explore the complete architecture and view 60+ additional features, check out our Technical Specifications.

Need more than just the backend?
You can explore our full catalog of production-ready boilerplates—including full-stack web and mobile ecosystems—at apptork.com.

Architecture

Root System relies on a containerized, polyglot architecture engineered for high concurrency and resilience:

graph TD
    Client(Flutter / Vue.js) <-->|REST API + SSE| Nginx(Nginx Reverse Proxy)
    Nginx <--> Gunicorn(Gunicorn + Uvicorn Workers)
    Gunicorn <--> Django(Django Application)
    Django --> Postgres(PostgreSQL)
    Django <--> Redis(Redis Message Broker)
    Django --> MinIO(MinIO / S3 Object Storage)

    Redis <--> Celery(Celery Workers)
    Celery <--> ThirdParty(OpenAI, Replicate, Custom GPUs)
    Celery --> MinIO
    Celery --> Postgres

    Redis <--> CeleryBeat(Celery Beat Scheduler)

Using the Makefile (Recommended)

This boilerplate includes a powerful Makefile that acts as a command hub. It abstracts away complex Docker arguments and automatically manages your Python virtual environments (.venv).

Throughout this documentation, we provide the fast make commands. However, if you are on Windows or don't have make installed, we have also provided the exact explicit Raw Command right below it so you don't have to guess any variables!

Quickstart Guide

Get the complete infrastructure running on your local machine in under 5 minutes.

1. Initialize Your Project

Run the backend initialization script to rebrand the boilerplate out of the box.

python init_backend.py

2. Configure Environment Variables

Copy the development environment files to set up your local workspace:

cp .env.local.example .env.local
cp .env.dev.example .env.dev
cp api/config/development.py.example api/config/development.py

3. Start the Stack

If you are actively developing and want immediate hot-reloading, use the override file:

cp docker-compose.override.yml.example docker-compose.override.yml

# Using Make (Recommended)
ENV=dev make dcrun

# Using Raw Docker Compose (Windows / No Make)
docker compose --env-file .env.dev up --build

Access the API at http://127.0.0.1:8000/

4. Setup Storage Keys (MinIO)

After your containers are running, you must configure the internal storage credentials. Ensure you have populated MINIO_ACCESS_KEY and MINIO_SECRET_KEY in your .env file with secure random strings, then run:

make minio-keys

5. Public URLs via Ngrok (Recommended)

If you are developing a mobile application on a physical device, or if you need to receive webhooks from monetization providers like RevenueCat or Lemon Squeezy, localhost URLs will not work because external devices/services cannot resolve your local machine.

Use the built-in Makefile commands to expose your local services to the internet via Ngrok.

Tip: Ngrok offers one free static domain per account. Claim it at https://dashboard.ngrok.com/domains (Navigate to Universal Gateway > Domains) so your webhook URLs don't change every time you restart your computer!

Expose MinIO (Required for mobile devices to download generated images):
```
make ngrok url=your-static-domain.ngrok-free.app
```
(Copy the forwarded URL, strip the https://, and set it as MINIO_ENDPOINT_URL in your .env.dev)
Expose the API (Required to receive webhooks):
```
make ngrokp port=8000 url=your-static-domain.ngrok-free.app
```
(Copy the forwarded URL and update your webhook dashboards accordingly)

You're all set!

Head over to your configured local host URL to interact with the API.

Project Structure

Overview of the key Django applications found in the api/ directory:

App Name	Description
`ai_core`	The unified AI orchestration interface and abstract BaseTask definitions.
`auth`	JWT token routing, multi-provider OAuth, and OTP pipelines.
`core`	System configuration, health checks, feature flags, and localized messages.
`files`	Object storage asset tracking.
`image_edit`	Image editing pipelines (e.g. outpainting, inpainting).
`image2image`	Image-to-image AI generation tasks.
`store`	E-commerce hooks linking RevenueCat/Stripe payloads to native Entitlements.
`text2image`	Text-to-image AI generation tasks.
`text2text`	Text-to-text generative AI tasks (LLMs).
`users`	User identity, profile metadata, and device analytics.
`wallets`	The immutable transactional virtual ledger and credit mechanisms.
`workflows`	The dynamic DAG engine for complex multi-step AI pipelines.