Skip to content

Architecture Overview

This page provides a high‑level view of ReFlux: what it contains, how the main components interact, and which principles guide the design.

ReFlux is a modular field service platform designed to support field service employees in their day‑to‑day operational work with minimal administrative effort.

Core principle:
Enter data once, reuse it everywhere.

System boundaries

What lives inside ReFlux

ReFlux covers the operational layer of field service execution:

  • Authentication and users

    • Password‑based authentication
    • Planned support for MFA via Microsoft Authenticator

  • Organizations and teams

    • Internal and external organizations
    • Team structures for grouping users and responsibilities

  • Service reporting

    • Planning and execution of field work
    • Service reports, approvals, abnormalities, and follow‑up
    • RAMS generation driven by templates and execution data

  • Timesheets

    • Internal timesheet registration
    • External timesheet document generation based on service orders
    • Reuse of timesheet data for reporting and approvals

  • Inventory context

    • Tools, PPE, parts, and stock references
    • Inventory data used as contextual input during service execution

  • Install base

    • Assets and units installed in the field
    • Install base used as context for service reports, spare parts, and RAMS

  • Planning

    • Engineer availability and scheduling
    • Work, travel, indirect time, and non‑working time
    • Planner‑driven time blocks supporting execution and timesheet suggestions

  • Manuals and instructions

    • Internal and external manuals
    • Instruction links attached to report templates and checkpoints

  • Notifications

    • Cross‑domain event notifications
    • Notifications triggered by service reports, inventory changes, and timesheets

  • Future capabilities

    • Internal chat
    • Live support chat

High‑level technical components

Backend

  • Architecture: Modular monolith
  • Framework: Django
  • API: REST (Django REST Framework)
  • Async processing: Celery

Frontend

  • Web: React
  • Mobile: React Native
  • Shared domain logic via common hooks/factories

Infrastructure

  • Docker-based deployment
  • Traefik reverse proxy
  • Single-host environment (currently development)

Data storage

  • PostgreSQL (primary database)
  • Redis (cache / queue)
  • File storage:
  • Local filesystem (current)
  • S3-compatible object storage (future)
flowchart LR
  %% ============================
  %% Client layer
  %% ============================
  WEB["Web App\n(React)"]
  MOB["Mobile App\n(React Native)"]
  %% Backend
  %% ============================
  API["Backend API\nDjango (REST)"]
  ASYNC["Async Processing\nCelery"]
  %% Infrastructure
  %% ============================
  DOCKER["Docker"]
  TRAEFIK["Traefik\nReverse Proxy"]
  %% Data stores
  %% ============================
  PG["PostgreSQL"]
  REDIS["Redis"]
  FS["Local File Storage"]
  S3["S3-compatible Storage\n(future)"]
  %% Flows
  %% ============================
  WEB --> TRAEFIK
  MOB --> TRAEFIK
  TRAEFIK --> API

  API --> PG
  API --> FS
  API --> S3

  API --> ASYNC
  ASYNC --> REDIS

  DOCKER --> TRAEFIK
  DOCKER --> API
  DOCKER --> ASYNC

Backend apps and domain responsibilities

ReFlux is structured as a modular monolith where each Django app owns a clear domain.

Platform & infrastructure

  • core – shared base models and utilities
  • jobs – background task definitions (Celery)
  • channels – real-time infrastructure (chat, future use)
  • django_celery_beat – scheduling
  • storages – storage abstraction

Identity & structure

  • accounts – users and authentication
  • orgs – organizations
  • teams – team structures

Core business domains

  • projects

    • Service orders (ReFlux representation)
    • Install base (assets and units)

  • servicereports

    • Report templates
    • Service reports (planning + execution)
    • RAMS generation
    • Abnormalities and follow‑up

  • timesheets

    • Internal timesheets
    • External timesheet documents

  • inventory

    • Tools, PPE, parts, stock references

  • manuals

    • Manuals, chapters, instructions

  • approvals

    • Approval workflows (primarily for internal timesheets)

  • notifications

    • Cross‑domain event notifications

  • chat

    • Internal and live support chat (future)

Domain relationship map (high level)

This diagram shows how major domains and apps relate, not how individual models interact.

flowchart LR
  ACC["accounts\nUsers"]
  ORGS["orgs\nOrganizations"]
  TEAMS["teams\nTeams"]

  SR["servicereports"]
  TS["timesheets"]
  INV["inventory"]
  APPR["approvals"]
  NOTIF["notifications"]

  USER["User"]
  ORG["Organization"]
  TEAM["Team"]

  ITS["Internal Timesheet"]
  ETS["External Timesheet"]
  SREP["Service Report"]

  %% Identity & structure
  ACC --> USER
  ORGS --> ORG
  TEAMS --> TEAM
  USER --> ORG
  USER --> TEAM

  %% Core execution
  SR --> SREP

  %% Timesheets
  TS --> ITS
  TS --> ETS

  %% Approvals
  APPR --> ITS

  %% Cross-domain links
  ETS --> SREP

  %% Notifications
  SR --> NOTIF
  TS --> NOTIF
  INV --> NOTIF
  NOTIF --> USER

Execution philosophy

Design‑time vs run‑time ReFlux strictly separates design-time configuration from run-time execution:

  • Templates define how work should be executed
  • Service reports capture how work was executed

This separation:

  • preserves historical accuracy
  • prevents template changes from affecting old reports
  • supports legal and operational auditability

Asynchronous processing

Background and deferred work is handled outside the request/response path.

flowchart LR
  API["Django REST API"]
  JOBS["jobs\nTask definitions"]
  CEL["Celery workers"]
  BEAT["django-celery-beat"]
  REDIS["Redis"]
  NOTIF["notifications"]

  API --> JOBS
  JOBS --> CEL
  BEAT --> CEL
  CEL --> REDIS
  CEL --> NOTIF

he jobs app is infrastructure-only and does not contain business domain entities. It defines background tasks that are executed asynchronously via Celery.

Key data flows (summary)

Service execution flow

  • An external case and ERP service order exist
  • The service order is represented in ReFlux
  • A service report is planned and executed
  • Abnormalities trigger follow-up actions (for example, Salesforce cases)
  • RAMS and documentation are generated from execution data

Timesheet reuse flow

  • Internal timesheets are entered once
  • The same data is reused for:
  • External timesheet documents
  • Organizational reporting
  • Approval workflows

Core architectural principles

Minimal effort to enter data

Reduce friction and error‑prone repetition by capturing data only when it is needed.

Minimal effort to reuse data

Ensure data flows cleanly across domains without requiring re-entry.

Enter once, reuse everywhere

Information entered via mobile or web is reused for reporting, documentation, and planning.

Freedom without license lock‑in

Support customization without costly platforms or vendor constraints.

Low external dependency footprint

Avoid brittle integrations and premature coupling to external systems.

Customization and extensibility

ReFlux supports:

  • Custom modules
  • Custom fields
  • Custom workflows
  • Template‑driven outputs (reports, RAMS, documents)

Customization is mainly developer‑driven, but intentionally approachable for anyone with basic Python and React knowledge.

Architecture support and guidance are provided by the system architect, Oliver Comes.

Non‑goals

ReFlux is not:

  • A full ERP
  • A payroll system
  • A BI platform
  • A low‑code platform
  • A replacement for SAP or Salesforce

ReFlux focuses explicitly on the operational execution layer of field service.