Skip to content

Core App

The core app provides the foundational infrastructure for the entire backend.

It is responsible for cross-cutting concerns that apply to all other apps, including:

  • multi-tenant request context (organization resolution)
  • permission handling and policy abstraction
  • audit logging
  • shared DRF utilities (mixins, exceptions)
  • file storage and upload validation
  • general backend utilities

Unlike feature apps, core does not represent a domain.
Instead, it defines how the system behaves internally.

Purpose

The core app exists to ensure:

  • consistent behavior across all apps
  • secure multi-tenant isolation
  • centralized authorization logic
  • traceability via audit logging
  • clean and maintainable architecture

All other apps (e.g. orgs, teams, projects) depend on core.

Key Responsibilities

1. Request Context Resolution

  • Resolves the active organization from request headers
  • Attaches request.org and request.customer_org
  • Enforces membership-based access

See: request-context.md

2. Permission System

  • Provides DRF permission classes (HasCurrentOrg, etc.)
  • Integrates with request context resolution
  • Acts as the bridge between HTTP and domain logic

See: permissions.md

3. Policy Layer (Authorization)

  • Defines reusable, domain-level permission logic
  • Replaces scattered role checks across services
  • Enables capability-based access control

Examples: - can_manage_org_members - can_manage_teams - can_view_team

See: policies.md

4. Audit Logging

  • Tracks all critical business actions
  • Stores structured change data
  • Links actions to actors and objects

Used across: - org membership changes - team updates - team membership lifecycle

See: audit.md

5. DRF Utilities

  • Mixins for common patterns (org scoping, audit fields)
  • Standardized API exception handling

See: - mixins.md - exceptions.md

6. Middleware

  • Lightweight entry point for request processing
  • Delegates context resolution to services

See: middleware.md

7. Storage & Uploads

  • Abstracts file storage (local vs S3)
  • Validates uploads (size, MIME type)

See: - storage.md - uploads.md

8. Utilities

  • Token generation
  • Shared helpers

See: tokens.md

Design Principles

The core app follows these principles:

Service-first architecture

All business logic lives in services, not views.

Thin views

Views only: - validate input - call services - return responses

Policy-based authorization

Authorization is: - centralized - reusable - testable

Explicit request context

No implicit globals — all org context comes from the request.

Strong auditability

All important changes are logged with: - actor - action - structured changes

How Other Apps Use Core

Typical flow in other apps:

  1. Request enters
  2. core.middleware resolves org context
  3. core.permissions validates access
  4. View calls service layer
  5. Service uses:
  6. core.policies for authorization
  7. core.audit for logging
  8. Response returned

When to Use Core

Use the core app when you need:

  • cross-app functionality
  • shared infrastructure
  • system-wide conventions

Do not put domain logic here.

When NOT to Use Core

Avoid placing in core:

  • business-specific logic (belongs in feature apps)
  • app-specific models or services
  • domain-specific permissions

Summary

The core app is the backbone of the backend system.

It ensures that all apps behave consistently, securely, and predictably —
especially in a multi-tenant environment.