System Architecture

Entirius is a Django backend built as a modular monolith, with an admin CMS and a storefront that reach it only through its REST API. The backend (Volkanos) is one deployable unit. Inside it sit 40+ Django modules with strict boundaries, listed in the Module Catalog. Not microservices (we don’t hate ourselves), and not one codebase where everything imports everything.

How It’s Wired

The CMS and the storefront are separate applications. They talk to the backend through the same API an external integrator would use. How the parts and the product names relate: Concepts.

A browser opens the two frontends, the storefront and the CMS. The modules fill the Matrix read model, and both the modules and Matrix keep their data in PostgreSQL.

Rules We Don’t Break

• Everything is an API. Modules expose REST endpoints, and v2 is the contract: its OpenAPI spec is generated from the code and Pydantic validates at run time. The storefront accounts endpoints are still v1 and sit outside the published spec; the accounts admin API is v2.
• Layers go one way. Models → services → API. Business logic lives in services. Views are thin. No exceptions, no “just this once.”
• Signals over imports. Modules that feed the storefront read model do it through Django signals, a Redis debounce set and Celery tasks. The PIM and price handlers are off until enabled; until then the read model is rebuilt by command.
• Security is not optional. JWT authentication for staff and customers, permission classes declared on every view, data scoped by channel. With the access module, an admin route is refused unless it is mapped to a permission area.

The decisions behind these rules:

• Access and API Tokens: staff roles per module area behind one admin gate, and hashed application tokens for the key routes
• Channels: why each module owns its Channel model, the three patterns, and how module channels are copied from PIM
• Languages: three ways to store translations and the fallback chain
• Signal-Driven Sync: how changes in PIM, prices and stock reach the read model

Decisions that concern one module live in that module’s repository.

One path through several modules, from a product in the catalog to an order in the CMS: Commerce Journey.

AI Toolbox

The AI features (message drafts, lead intel, translations) call a separate, non-public AI toolbox over HTTP through the shared client in entirius-django-utils (django_utils.toolbox), authenticated with an X-API-Key header. States, fallbacks and settings: AI Toolbox.

Technology Stack

Part	Technology
Language and framework	Python 3.12+, Django 5.2+, Django REST Framework
Validation and API spec	Pydantic, drf-spectacular
Database	PostgreSQL
Cache and debounce state	Redis
Background work	Celery worker and beat
Admin CMS	Admin CMS
Storefront	Storefront

How the modules are built and by whom: What Entirius Is.

Next

Channels