DjangoPlay — Product Overview

#1. Overview

It provides a structured application platform around:

• Domain-oriented Django apps
• Service-layer business logic
• Centralized authentication and authorization
• REST APIs and API documentation
• Background task processing
• Auditability and system events
• Reusable integrations
• Financial and business-domain capabilities
• Issue tracking and helpdesk workflows
• In-app AI capabilities
• Development and operational tooling

DjangoPlay follows a modular monolith architecture. Its capabilities are separated into Django applications and service boundaries while remaining part of a single primary Django deployment.

The goal is to provide a strong application foundation without introducing the operational complexity of a distributed microservice architecture too early.

#2. What DjangoPlay Is

DjangoPlay is not a single-purpose business application.

It is a Django application platform containing reusable infrastructure, domain modules, security mechanisms, integrations, and developer tooling that can be used together as one system.

At a high level:

                         DjangoPlay
                             │
             ┌───────────────┼────────────────┐
             │               │                │
             ▼               ▼                ▼
          Web UI         REST APIs       Background Jobs
             │               │                │
             └───────────────┼────────────────┘
                             ▼
                    Application Services
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
           Domains       Policies       Integrations
              │              │              │
              └──────────────┼──────────────┘
                             ▼
                     Platform Infrastructure
                  PostgreSQL • Redis • Celery
                             │
                             ▼
                           AuthX
`

The detailed architecture is documented separately in the architecture documentation.

#3. Platform Capabilities

#4. Application Structure

DjangoPlay is composed of Django applications with explicit responsibilities.

The current platform includes the following major applications and components:

The applications are documented individually in the application documentation.

#5. Architectural Model

DjangoPlay uses a modular monolith with layered, service-oriented application design.

A typical request follows this general path:

Client
  │
  ▼
URL Routing
  │
  ▼
Web View / API View
  │
  ▼
Serializer / Request Validation
  │
  ▼
Service Layer
  │
  ├── Authorization / Policy
  ├── Domain Rules
  ├── Queries
  ├── Audit / Events
  ├── Integrations
  └── Background Tasks
  │
  ▼
Domain Models
  │
  ▼
PostgreSQL

The architecture deliberately keeps HTTP concerns separate from business decisions.

The service layer is the primary application boundary for business operations and workflows.

#6. Domain-Oriented Design

DjangoPlay separates platform capabilities into domains and supporting infrastructure.

Examples include:

#Identity & Access

• users
• policyengine
• teamcentral
• AuthX integration

#Business Domains

• entities
• locations
• industries
• invoices
• fincore
• helpdesk

#Platform Services

• core
• audit
• mailer
• apidocs
• utilities
• devtools

#Presentation

• frontend

#AI

• aicore

#Integrations

• paystream.integrations
• Generic Issue Tracker integration
• AuthX
• Email providers
• AI providers
• Cloud services and external APIs

This structure allows individual capabilities to evolve without turning the entire application into one tightly coupled domain.

#7. Identity and Authentication

DjangoPlay integrates with AuthX Identity, a standalone identity service.

AuthX is the identity authority and sole JWT signing authority for the AuthX authentication architecture.

The relationship is:

                         AuthX
                           │
                           │ signs JWT
                           ▼
                          JWT
                           │
                           │ verified by
                           ▼
                      DjangoPlay

DjangoPlay communicates with AuthX through a dedicated backend integration and service credential.

Additional authentication functionality includes:

• Django sessions
• django-allauth
• Google OAuth / social login
• User signup and verification
• Password reset
• SSO onboarding

Authentication architecture is documented separately.

#8. Authorization and Security

Authorization is treated as a platform-level concern.

The policyengine application provides centralized permission and role evaluation rather than requiring every domain application to implement unrelated access rules.

The platform follows a fail-closed authorization model: access should be denied when the required authorization decision cannot be established.

Security capabilities include:

• Authentication
• Role and permission evaluation
• Policy enforcement
• Request validation
• CSRF protection
• CORS controls
• Rate limiting and throttling
• Security headers
• Protected credentials
• Encrypted configuration secrets
• Abuse/bot protection where enabled
• Auditability of meaningful system actions

Detailed security mechanisms and configuration are documented separately.

#9. Event and Audit Architecture

DjangoPlay includes a central domain-event mechanism in core.

Business operations can emit domain events which are consumed by independent subscribers.

One important consumer is the audit application.

Conceptually:

Business Operation
       │
       ▼
   Domain Event
       │
       ├──────────► Audit
       │
       ├──────────► Logging
       │
       └──────────► Telemetry / Other Subscribers

The audit subsystem provides an append-only, lifecycle-oriented audit trail with support for concerns such as:

• State changes
• Model history
• Actor attribution
• Diff information
• PII governance
• Sanitization
• Retention

Audit processing is intentionally separated from core business logic.

#10. Generic Issue Tracker Integration

DjangoPlay uses the reusable Generic Issue Tracker as its issue-management foundation.

The third-party package provides the reusable issue-tracking functionality while DjangoPlay keeps its application-specific behavior inside:

paystream.integrations.issuetracker

This boundary allows DjangoPlay to:

• Integrate issue tracking into the platform
• Bridge helpdesk workflows
• Apply DjangoPlay-specific visibility and access rules
• Extend integration behavior without modifying the third-party package
• Upgrade the underlying issue-tracker package independently

The Issue Tracker is exposed through a dedicated issues subdomain while remaining part of the DjangoPlay deployment.

#11. Financial and Business Capabilities

DjangoPlay contains several business-oriented modules.

#teamcentral

Provides organizational functionality including:

• Members
• Employment
• Departments
• Teams
• Roles
• Leave management

#entities

Provides business/entity records suitable for CRM-style application workflows.

#locations

Provides geographic reference data and address/location functionality.

#industries

Provides industry classification and reference data including CPC/HS classifications.

#fincore

Provides the underlying financial domain functionality used by financial workflows.

#invoices

Provides invoicing and related functionality including:

• Invoices
• Billing schedules
• Payments
• GST configuration

These modules are documented individually and should not be treated as one monolithic business domain.

#12. AI Capabilities

DjangoPlay includes the aicore application, providing an authenticated, streaming AI assistant.

The AI layer uses a provider abstraction so that application logic is not tied to a single model provider.

Supported integration patterns include:

• xAI
• OpenAI
• OpenAI-compatible custom providers
• Local providers such as Ollama

The AI implementation supports application-level controls such as rate limiting and conversation/session persistence.

Detailed provider configuration, model selection, streaming behavior, usage controls, and BYOK security are documented in the dedicated aicore documentation.

#13. REST API and Developer Portal

DjangoPlay uses Django REST Framework as its API framework.

The API platform provides:

• API Views and ViewSets
• Serializers
• Authentication
• Authorization
• Validation
• Throttling
• Versioned API routing
• OpenAPI schema generation
• Swagger UI
• ReDoc

The apidocs application provides the API documentation portal and associated API request logging.

The generated API schema follows OpenAPI 3.x conventions and is presented through a customized Swagger/ReDoc developer experience.

#14. Background Processing

DjangoPlay uses Celery with Redis for asynchronous work.

Typical background operations include:

• Email delivery
• External API calls
• File processing
• Data processing
• Long-running workflows
• Integration synchronization
• Scheduled maintenance operations

The general execution model is:

Application Service
       │
       ▼
   Celery Task
       │
       ▼
      Redis
       │
       ▼
 Celery Worker
       │
       ▼
External Service / Database / Other Work

Background processing keeps long-running or non-critical operations outside the HTTP request lifecycle.

#15. Email and Communication

The mailer application provides centralized transactional email functionality.

It handles concerns such as:

• Email templates
• SMTP/provider configuration
• Verification emails
• Password-reset messages
• Support and issue-related messages
• Throttling
• Unsubscribe handling

Email behavior is kept out of individual domain applications wherever practical.

#16. Configuration and Secrets

DjangoPlay separates structured configuration from sensitive credentials.

The deployment configuration is organized under:

~/.dplay/
├── .secrets
├── .authx
├── config.yaml
└── .appdata

The files have distinct responsibilities:

DjangoPlay also provides encrypted secret handling so sensitive application configuration can be stored encrypted at rest before being loaded into the application environment.

The complete key-by-key configuration reference is maintained separately.

#17. Development and Operational Tooling

DjangoPlay includes tooling for development, provisioning, diagnostics, and data preparation.

The platform uses the external djangoplay-cli command:

dplay

The CLI provides commands for operations such as:

• Starting Django with HTTP or HTTPS
• Running Celery workers
• Managing the local development environment
• Generating local SSL certificates
• Checking environment health
• Resetting local infrastructure

The devtools application provides Django management commands for:

• Development data generation
• Reference-data import
• Reference-data synchronization
• Finance-related data generation
• Administrative scripting
• Other repeatable development workflows

#18. Production Infrastructure

The current production topology is intentionally compact.

Cloudflare
     │
     ├── djangoplay.org
     │      └── Static Cloudflare Pages site
     │
     ├── docs.djangoplay.org
     │      └── Static Cloudflare Pages documentation
     │
     └── app / issues
            │
            ▼
        GCP VM
            │
       ┌────┼──────────────┐
       ▼    ▼              ▼
     Nginx Django       Celery
           │              │
           │            Redis
           │
      PostgreSQL
           │
         AuthX

The current deployment uses:

• Cloudflare DNS
• Cloudflare Pages
• GCP VM
• Nginx
• Gunicorn
• Django
• Celery
• Redis
• PostgreSQL
• AuthX Identity
• Cloudflare R2
• Cloudflare Turnstile where enabled

The app and issues hosts are dynamically served by Django, while the portfolio and documentation sites are static.

The detailed infrastructure and deployment architecture is documented separately.

#19. Deployment and Delivery

GitLab is the primary source-control and CI/CD platform for DjangoPlay.

Production deployment is performed through GitLab CI/CD.

The deployment pipeline is responsible for operations such as:

GitLab
   │
   ▼
CI/CD Pipeline
   │
   ▼
Production Server
   │
   ├── Pull main
   ├── Install/update dependencies
   ├── Run migrations
   ├── Collect static assets
   └── Restart Django/Celery services

GitHub is maintained as a repository mirror rather than being the primary deployment source.

Detailed deployment, CI/CD, release, and infrastructure procedures are documented separately.

#20. External Integrations

DjangoPlay maintains explicit integration boundaries for external systems.

Important integrations include:

DjangoPlay-specific integration code is kept in dedicated integration boundaries rather than being scattered through domain applications.

#21. Architectural Characteristics

#22. Design Philosophy

DjangoPlay is built around several architectural principles.

#Domain Ownership

Each application owns a specific domain or platform capability rather than becoming a collection of unrelated functionality.

#Service-First Business Logic

Business decisions and state-changing workflows belong in services rather than accumulating inside views.

#Protected Identity Boundary

Identity and JWT issuance are delegated to AuthX, keeping identity authority outside ordinary domain application logic.

#Centralized Authorization

Permission decisions are handled through the policy system rather than duplicated across individual applications.

#Auditability

Important system activity is designed to remain observable, attributable, and auditable.

#Fail-Closed Security

Security-sensitive decisions default toward denial when the required authorization context is unavailable.

#Explicit Integration Boundaries

External providers and reusable third-party components are integrated through defined boundaries to reduce coupling.

#Operational Simplicity

The system currently favors a modular monolith and compact infrastructure over premature distribution into microservices.

#23. Documentation

This document is the product-level overview.

It intentionally does not reproduce the implementation details of every Django app, configuration key, security mechanism, integration, or deployment procedure.

Detailed documentation is maintained separately at:

https://docs.djangoplay.org/

Major documentation areas include:

• High-Level Architecture
• Application Architecture
• Authentication Architecture
• Security Architecture
• Infrastructure Architecture
• Integration Architecture
• Deployment
• Scaling
• Configuration
• Development Tooling
• Individual Application Documentation

The complete application documentation covers architecture, functionality, models, services, integrations, and implementation details for each major application.

#24. Summary

DjangoPlay is a production-oriented modular Django / DRF platform that combines business-domain applications with reusable platform capabilities.

Its architecture brings together:

• Domain-oriented Django applications
• Service-layer business logic
• AuthX-based identity
• Centralized authorization
• Domain events and auditability
• REST APIs
• Celery-based background processing
• PostgreSQL and Redis
• Generic Issue Tracker integration
• Provider-agnostic AI capabilities
• Centralized email services
• Developer and operational tooling
• Cloud-based production infrastructure
• GitLab CI/CD

The result is a practical middle ground between a tightly coupled traditional Django application and a highly distributed microservice system.

DjangoPlay remains deployable as a coherent modular monolith while maintaining boundaries that allow individual capabilities and integrations to evolve independently as the platform grows.