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 ⚙️ Core Concepts

Overview

The Apptork Root System serves as the backend infrastructure to scale products rapidly while avoiding hundreds of hours of redundant engineering. Built with Django 5.2, PostgreSQL, and Redis, it offers:

Asynchronous AI Orchestration: Celery-based background processing for heavy AI inference loads.
Monetization Engine: Turnkey webhook handling for RevenueCat and Lemon Squeezy, alongside an immutable transactional wallet ledger.
Real-Time Data Flow: Server-Sent Events (SSE) natively integrated to stream generation statuses to the client without polling.
Absolute Environment Parity: Fully containerized setup mimicking AWS/production down to local MinIO object storage.

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 <--> Daphne(Daphne ASGI Server)
    Daphne <--> 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://localhost: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.
`store`	E-commerce hooks linking RevenueCat/Stripe payloads to native Entitlements.
`wallets`	The immutable transactional virtual ledger and credit mechanisms.
`users`	User identity, profile metadata, and device analytics.
`workflows`	The dynamic DAG engine for complex multi-step AI pipelines.