Skip to content

Backend Overview

The ReFlux backend provides the core business logic, data integrity, and integration layer of the platform. It is designed to be robust, extensible, and predictable, while remaining approachable for developers working on real operational features.

Architecturally, the backend follows a modular monolith approach: a single deployable Django application, internally structured into clear domain-focused apps.

Responsibilities

The backend is responsible for:

  • Business logic and domain rules
    Enforcing workflows, validations, and state transitions while preventing invalid or inconsistent data across domains.

  • Data persistence and integrity
    Storing operational data such as service reports, timesheets, and inventory context, and enforcing organizational boundaries and relationships.

  • API exposure
    Providing REST APIs for web and mobile clients and acting as the single source of truth for all application data.

  • Asynchronous and background processing
    Handling deferred or non‑blocking work such as notifications and scheduling recurring or delayed tasks.

  • Integration with external systems
    Exchanging data with ERP and CRM systems (for example SAP and Salesforce), acting as an orchestration layer rather than a replacement.

  • Security and access control
    Enforcing authentication and authorization rules and ensuring auditability of sensitive operations.

Key building blocks

Django apps

The backend is structured into Django apps, each owning a specific responsibility or business domain. This keeps boundaries explicit while allowing controlled cross-app interaction where necessary.

Key app categories include:

  • Platform & infrastructure

    • Shared base models and utilities
    • Background task definitions
    • Real‑time and scheduling infrastructure

  • Identity & structure

    • Users, organizations, and teams

  • Core business domains

    • Projects, service reports, timesheets, inventory, manuals, approvals, notifications

Each app owns its models and core business rules. Other apps may reference those models, but ownership remains clear.

DRF APIs

The backend exposes functionality via REST APIs using Django REST Framework (DRF).

API characteristics:

  • Stateless request/response model
  • Explicit serializers defining input/output shapes
  • Validation at both serializer and model level
  • Clear separation between:
  • transport concerns (API layer)
  • domain logic (models, services)

The API serves both: - the web client (React) - the mobile client (React Native)

Background tasks

Background and deferred work is handled asynchronously using Celery.

Typical use cases include:

  • Sending notifications
  • Performing follow‑up or housekeeping actions
  • Running scheduled or delayed tasks

Background tasks are defined in the backend but executed outside the request/response cycle to keep APIs responsive and predictable.

Important: background tasks are infrastructure concerns and do not represent business domain entities themselves.

Integration points

ReFlux integrates with external systems rather than replacing them.

Key characteristics of integrations:

  • ReFlux owns its internal representation of external concepts (e.g. service orders)
  • ERP/CRM systems remain authoritative for financial and commercial data
  • Integrations are explicit and narrowly scoped
  • Failures or delays in external systems should not corrupt internal state

This keeps ReFlux resilient while still fitting into a larger system landscape.

Request lifecycle

At a high level, an incoming request follows this sequence:

1. Transport
The HTTP request enters the system via the Django application and is routed to the appropriate endpoint.

2. Middleware
Cross‑cutting concerns are applied, such as security checks, organization resolution, and request context setup.

3. Authentication
The identity of the caller is resolved and credentials (for example tokens) are validated.

4. Authorization and permissions
Access rights are evaluated based on roles, organization, and ownership rules. Unauthorized requests are rejected early.

5. Validation
Incoming data is validated at the API layer, after which domain invariants are enforced at the model level.

6. Business logic execution
Domain rules, workflows, and state transitions are applied in a controlled and predictable manner.

7. Persistence
Validated changes are committed to the database. Audit and history mechanisms may record the change.

8. Response
A structured response is returned to the client. Side effects may be executed or scheduled asynchronously.

This layered approach ensures correctness, predictable behavior, and traceability of changes.

What this page intentionally does not cover

This overview deliberately avoids low‑level details such as:

  • individual model fields
  • serializer implementations
  • exact permission matrices
  • per-app API endpoints

Those details are documented in the app‑specific backend pages that follow.