Services¶

The core.services package provides shared, system-level functionality used across all apps.

Unlike feature apps, the core service layer does not implement business workflows.
Instead, it provides infrastructure services that support the entire backend.

Purpose¶

Core services exist to:

centralize cross-cutting logic
keep middleware and views thin
provide reusable system utilities
ensure consistent behavior across apps

Scope of Core Services¶

The core service layer currently includes:

request context resolution
audit logging

These services are foundational and used by many other apps.

Design Principles¶

Core services follow the same principles as other service layers:

Framework-independent¶

no DRF-specific logic
minimal dependency on HTTP

Reusable¶

callable from any app
consistent behavior across the system

Explicit¶

no hidden side effects
clear inputs and outputs

Focused¶

each service has a well-defined responsibility

Available Services¶

1. Request Context Service¶

Located in:

core.services.request_context

Responsibility¶

resolve the active organization from request headers
validate user membership
attach org context to the request

Main Functions¶

resolve_current_org(request)
resolve_current_customer_org(request)
attach_current_org(request)
attach_current_customer_org(request)

Usage¶

Used by: - middleware - permission classes

Not typically used directly by views.

2. Audit Service¶

Located in:

core.services.audit

Responsibility¶

create structured audit log entries
provide query helpers for audit data

Main Functions¶

log_audit(...)
list_audit_logs_for_object(...)
list_audit_logs_for_actor(...)
list_audit_logs_for_action(...)

Usage¶

Used by: - service layers in feature apps - any code performing state-changing operations

Service Interaction Flow¶

flowchart LR
    A[Request] --> B[Middleware]
    B --> C[Request Context Service]
    C --> D[Permissions]
    D --> E[View]
    E --> F[Feature Service]
    F --> G[Audit Service]

How Core Services Are Used¶

Request Context¶

middleware calls attach_current_org
permissions ensure valid context
views access request.org
services receive org as argument

Audit Logging¶

feature services call log_audit
audit entries are persisted centrally
logs can be queried for debugging or analytics

Responsibilities vs Other Layers¶

Core Services¶

infrastructure logic
system-wide behavior
cross-app utilities

Feature Services (e.g. orgs, teams)¶

business workflows
domain rules
validation and state transitions

What Core Services Should NOT Do¶

Core services should not:

implement domain-specific workflows
contain business rules tied to a single app
depend on serializers or views
perform permission decisions (use policies instead)

Example Usage¶

Request Context¶

Middleware:

calls attach_current_org(request)
request.org becomes available

Permission:

checks request.org
denies access if missing

Audit Logging¶

Inside a service:

log_audit(
    instance=team,
    actor=user,
    action="team.updated",
    changes={
        "name": {"old": "A", "new": "B"}
    },
    request=request,
)

Error Handling¶

Core services:

raise Python exceptions
do not return HTTP responses

Handling is done in:

views
DRF exception handler

Benefits¶

Core services provide:

consistency across apps
reduced duplication
centralized infrastructure logic
easier testing and debugging

Future Extensions¶

The core service layer can be extended with:

caching utilities
background job helpers
notification services
feature flag evaluation
rate limiting helpers

Summary¶

The core.services package provides the foundational infrastructure for the backend.

It enables:

clean request context handling
consistent audit logging
reusable system-level functionality

All feature apps rely on these services to ensure consistent and predictable behavior.