--- since: 1.2.1 --- # DjangoPlay — Product Overview ## 1. Overview **DjangoPlay** is a modular Django / Django REST Framework platform designed as a reusable foundation for building production-oriented business applications. 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: ```text 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 | Capability | Purpose | | --------------------- | ----------------------------------------------------------------------------- | | Web Application | Server-rendered Django application and user-facing workflows | | REST APIs | Django REST Framework APIs with versioned routing and validation | | Identity | Authentication and identity integration through AuthX | | SSO | Social authentication and SSO onboarding, including Google OAuth | | Authorization | Centralized role, permission, and policy evaluation | | Domain Modules | Business and platform functionality organized as Django apps | | Financial Platform | Finance, invoicing, billing, payments, and GST-related functionality | | Organizations | Teams, members, employment, departments, roles, and organizational structures | | Business Entities | CRM-style business/entity records | | Geolocation | Geographic reference data and location/address functionality | | Helpdesk | Support and bug-report workflows | | Issue Tracking | Integration with the reusable Generic Issue Tracker | | Audit | Platform-wide append-only audit trail and lifecycle tracking | | Email | Transactional email, templates, throttling, and unsubscribe handling | | Background Processing | Celery-based asynchronous processing | | AI | Provider-agnostic in-app streaming AI assistant | | API Documentation | OpenAPI schema, Swagger UI, and ReDoc | | Developer Tooling | Management commands, data generation, import/sync tooling, and diagnostics | | Frontend | Application templates, UI shell, static assets, and asset packaging | | Configuration | Structured deployment configuration and protected secrets handling | --- ## 4. Application Structure DjangoPlay is composed of Django applications with explicit responsibilities. The current platform includes the following major applications and components: | Component | Responsibility | | ------------------------------------- | -------------------------------------------------------------------------------------------------- | | `core` | Cross-cutting runtime infrastructure, execution context, domain events, and telemetry | | `users` | Users, authentication workflows, signup, verification, password reset, and SSO onboarding | | `policyengine` | Centralized permissions, roles, policies, and feature-flag evaluation | | `teamcentral` | Organizational structure, members, employment, departments, teams, roles, and leave | | `entities` | Business/entity records | | `locations` | Geographic reference data and address/location functionality | | `industries` | Industry classification and CPC/HS reference data | | `fincore` | Core financial functionality | | `invoices` | Invoices, billing schedules, payments, and GST-related configuration | | `helpdesk` | Support tickets and bug-report workflows | | `mailer` | Transactional email delivery, templates, throttling, and unsubscribe handling | | `audit` | Platform-wide audit lifecycle and append-only audit records | | `apidocs` | OpenAPI schema, Swagger/ReDoc developer portal, and API request logging | | `aicore` | In-app streaming AI assistant | | `devtools` | Development-data generation, reference-data import/sync, and management tooling | | `frontend` | Templates, frontend assets, UI shell, and asset packaging | | `utilities` | Shared framework utilities, admin infrastructure, validators, exports, and reusable API components | | `paystream` | Django project package containing settings, URL configuration, security tooling, and integrations | | `genericissuetracker` | Reusable third-party issue-tracking Django package | | `paystream.integrations.issuetracker` | DjangoPlay-specific Issue Tracker integration and adapter layer | 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text ~/.dplay/ ├── .secrets ├── .authx ├── config.yaml └── .appdata ``` The files have distinct responsibilities: | File | Purpose | | ------------- | --------------------------------------------------- | | `.secrets` | DjangoPlay sensitive configuration and credentials | | `.authx` | AuthX Identity deployment configuration | | `config.yaml` | Structured application and deployment configuration | | `.appdata` | Optional reference-data configuration | 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: ```text 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. ```text 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: ```text 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: | Integration | Purpose | | --------------------- | ------------------------------------------------------- | | AuthX Identity | External identity and authentication authority | | Generic Issue Tracker | Reusable issue-management platform | | Email / SMTP | Transactional email delivery | | Google OAuth | Social authentication / SSO | | AI Providers | AI inference for `aicore` | | Cloudflare | DNS, edge services, Turnstile, and CDN-related services | | Cloudflare R2 | Object storage and frontend asset distribution | | External APIs | Domain-specific or platform integrations | DjangoPlay-specific integration code is kept in dedicated integration boundaries rather than being scattered through domain applications. --- ## 21. Architectural Characteristics | Area | Current Approach | | --------------------- | ------------------------------------------- | | System Architecture | Modular Monolith | | Web Framework | Django 5.2 | | API Framework | Django REST Framework | | Application Design | Layered / Service-Oriented | | Domain Structure | Django Apps as Modules | | Authentication | AuthX + Django authentication ecosystem | | JWT Authority | AuthX | | Authorization | Centralized Policy Engine | | Events | Domain Event Bus | | Audit | Append-only lifecycle-oriented audit system | | Database | PostgreSQL | | Cache / Broker | Redis | | Background Processing | Celery | | API Documentation | OpenAPI / Swagger / ReDoc | | Issue Management | Generic Issue Tracker | | AI | Provider-agnostic `aicore` | | Web Server | Nginx | | Application Server | Gunicorn | | Edge / CDN | Cloudflare | | Object Storage | Cloudflare R2 | | CI/CD | GitLab CI/CD | | Development CLI | `djangoplay-cli` | --- ## 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/](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.