Skip to content

Project Structure

This page describes how the ReFlux backend codebase is organized and where different responsibilities live.

The backend is implemented as a modular monolith using Django. The structure is designed to keep domain ownership clear while avoiding unnecessary fragmentation into microservices.

Top‑level layout

At a high level, the backend consists of:

  • A single Django project responsible for configuration and routing
  • Multiple Django apps, each owning a specific domain
  • Shared infrastructure libraries used across apps

The backend is deployed as one logical application, but internally organized to scale as the system grows.

Configuration and settings

Global configuration lives at the project level and applies to all apps.

This includes:

  • Django settings (environments, middleware, installed apps)
  • REST framework configuration
  • Authentication and security configuration
  • Logging, task queues, and storage backends

Environment-specific configuration is handled via settings separation and deployment configuration rather than per-app overrides.

URL routing

The backend exposes a single, versioned API surface.

All application APIs are mounted under a shared prefix: /api/v1/ The main URL configuration is responsible only for:

  • admin access
  • API documentation
  • authentication utilities
  • delegating routing to domain apps

Each domain app registers its own URLs and is included at the project level.

Key characteristics of the URL layout:

  • One global API version (v1)
  • No cross-app URL imports
  • Apps own their own routes and namespaces

Application routing map

The backend routes requests to domain apps as follows:

  • Core platform routes
    core, accounts, orgs, teams

  • Operational domains
    projects, servicereports, timesheets, inventory, manuals

  • Workflow and system domains
    approvals, notifications, chat

  • Infrastructure and background processing
    jobs

Some domains use explicit sub‑paths where useful (for example approvals and timesheets), but the routing philosophy remains consistent: the project layer coordinates, apps own behavior.

Django apps (domain ownership)

Each Django app owns:

  • Its database models
  • Its serializers and validation rules
  • Its API views and URL definitions
  • Its domain-specific business logic

Apps may reference models from other domains, but ownership and authority remain clear.

Domains are intentionally coarse-grained to avoid tight coupling and excessive inter-app dependencies.

Shared libraries and cross‑cutting concerns

Certain functionality is shared across multiple apps and lives in common locations:

  • Base models (timestamps, org scoping, audit fields)
  • Permission and access helpers
  • Shared utilities and abstractions
  • Background task infrastructure (Celery integration)

These shared components are designed to support domain logic, not replace it.

Background processing and infrastructure apps

Infrastructure-related apps provide capabilities used by business domains but do not define business entities themselves.

Examples include:

  • Background task definitions and execution
  • Scheduled jobs
  • Real-time communication infrastructure

These apps are deliberately isolated from domain models to prevent business logic from leaking into infrastructure layers.

API documentation endpoints

The backend exposes built-in API documentation to support development and integration:

  • OpenAPI schema endpoint
  • Interactive API documentation (Swagger UI)

These endpoints are part of the project-level routing and apply to all apps.

Design intent

This structure is designed to:

  • Keep domain ownership explicit
  • Avoid circular dependencies
  • Encourage incremental growth of functionality
  • Support customization without structural rewrites

Low-level implementation details (models, serializers, services) are documented in the domain-specific backend pages that follow.