--- since: 1.2.1 --- # **DjangoPlay — Infrastructure Architecture** **Date:** 2026-08-29 --- ## **1. Overview** DjangoPlay uses a deliberately simple production infrastructure designed around a small GCP virtual machine, Cloudflare-managed DNS and edge services, and separate static hosting for the portfolio and documentation sites. The current production architecture is: - **Cloudflare** for DNS, edge protection, and static site delivery - **GCP e2-micro VM** for the DjangoPlay application runtime - **Nginx** as the web server and reverse proxy - **Gunicorn** as the Django WSGI application server - **Celery** for asynchronous background processing - **Redis** for caching and Celery messaging - **PostgreSQL** as the primary application database - **AuthX** as the identity service - **Cloudflare R2** for object storage used by supported asset/reference-data workflows - **Cloudflare Turnstile** for optional bot and abuse protection ![DjangoPlay Architecture Overview](../diagrams/djangoplay-architecture-overview.png) The infrastructure intentionally remains small and operationally simple. The application is structured as a modular monolith so that individual components can be scaled or separated later without requiring that architecture today. --- ## **2. DjangoPlay Cloud Infrastructure** Production traffic is managed through Cloudflare and routed to the appropriate hosting environment. ```mermaid flowchart TD DNS["Cloudflare DNS
djangoplay.org zone"] DNS --> CF DNS --> GCP subgraph CF["Cloudflare"] PAGES["Cloudflare Pages
Static hosting / global edge delivery"] SITE["djangoplay.org
Portfolio + developer site"] DOCS["docs.djangoplay.org
System documentation"] PAGES --> SITE PAGES --> DOCS end subgraph GCP["GCP e2-micro VM
Production runtime"] NGINX["Nginx
Web server / reverse proxy"] APP["DjangoPlay
Gunicorn + Django"] CELERY["Celery
Background workers"] AUTHX["AuthX
Identity service"] REDIS["Redis
Cache / Celery broker"] POSTGRES["PostgreSQL
Application database"] NGINX --> APP APP --> AUTHX APP --> POSTGRES APP --> REDIS APP --> CELERY CELERY --> REDIS CELERY --> POSTGRES end GCP --> R2["Cloudflare R2
Object storage / asset workflows"] APP --> TURNSTILE["Cloudflare Turnstile
Bot / abuse protection"] classDef dns fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a classDef cloudflare fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c classDef runtime fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b classDef service fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444 classDef external fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91 class DNS dns class CF,PAGES cloudflare class GCP runtime class SITE,DOCS,NGINX,APP,CELERY,AUTHX,REDIS,POSTGRES service class R2,TURNSTILE external ```` ### **Cloud Infrastructure Responsibilities** | Component | Responsibility | | ------------------------ | ---------------------------------------------------------------------------- | | **Cloudflare DNS** | DNS management and traffic entry for the DjangoPlay domain | | **Cloudflare Pages** | Static hosting and global delivery for the portfolio and documentation sites | | **GCP e2-micro VM** | Production runtime for DjangoPlay and its supporting services | | **Nginx** | Public web entry point, reverse proxy, and TLS termination | | **DjangoPlay** | Main Django application | | **Gunicorn** | WSGI application server for Django | | **Celery** | Asynchronous background task processing | | **AuthX** | Identity service used by DjangoPlay authentication flows | | **Redis** | Application cache and Celery broker | | **PostgreSQL** | Primary persistent application database | | **Cloudflare R2** | Object storage used by supported asset/reference-data workflows | | **Cloudflare Turnstile** | Optional bot and abuse protection | --- ## **3. Production Runtime Architecture** The GCP VM contains the primary DjangoPlay runtime components. ```mermaid flowchart TD INTERNET["Internet"] INTERNET --> NGINX["Nginx
Reverse proxy / TLS"] subgraph VM["GCP e2-micro Production VM"] NGINX --> GUNICORN["Gunicorn
WSGI server"] GUNICORN --> DJANGO["DjangoPlay
Modular Django application"] DJANGO --> POSTGRES["PostgreSQL
Persistent application data"] DJANGO --> REDIS["Redis
Cache / broker"] DJANGO --> AUTHX["AuthX
Identity service"] DJANGO --> CELERY["Celery Tasks"] CELERY --> REDIS CELERY --> POSTGRES end DJANGO --> EMAIL["SMTP / Email Provider"] DJANGO --> EXTERNAL["External APIs"] DJANGO --> R2["Cloudflare R2"] classDef internet fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a classDef runtime fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b classDef storage fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444 classDef external fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91 class INTERNET internet class VM,GUNICORN,DJANGO,CELERY runtime class NGINX,POSTGRES,REDIS,AUTHX storage class EMAIL,EXTERNAL,R2 external ``` ### **Runtime Flow** The normal web request path is: ```text Internet │ ▼ Nginx │ ▼ Gunicorn │ ▼ DjangoPlay │ ├── PostgreSQL ├── Redis ├── AuthX └── Celery │ └── Redis → Worker → External Service ``` Nginx handles the public HTTP(S) boundary while Gunicorn serves the Django application. DjangoPlay uses PostgreSQL for persistent application state and Redis for cache and asynchronous task messaging. AuthX is a distinct identity service within the production runtime and is consumed by DjangoPlay for identity-related authentication flows. --- ## **4. DjangoPlay Host Application Architecture** DjangoPlay is implemented as a modular monolith. Domain applications are deployed together as one Django project while maintaining separation of responsibilities. ```mermaid flowchart TD APP["DjangoPlay
Modular Monolith"] APP --> IDENTITY["Identity & Access
users / teamcentral / policyengine"] APP --> BUSINESS["Business Domains
invoices / fincore / entities / helpdesk"] APP --> MASTER["Master Data
locations / industries"] APP --> INFRA["Application Infrastructure
audit / mailer / apidocs"] APP --> FRONTEND["Presentation
frontend"] APP --> INTEGRATIONS["Integrations
external systems / issue tracker"] IDENTITY --> AUTHX["AuthX"] BUSINESS --> DB["PostgreSQL"] MASTER --> DB INFRA --> DB INTEGRATIONS --> EXTERNAL["External Services"] classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b classDef domain fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444 classDef external fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91 class APP app class IDENTITY,BUSINESS,MASTER,INFRA,FRONTEND,INTEGRATIONS domain class AUTHX,DB,EXTERNAL external ``` The host application remains a single deployable Django system while domain boundaries are maintained within the codebase. --- ## **5. DjangoPlay Internal Infrastructure** The host application relies on several shared infrastructure capabilities. | Component | Purpose | | ------------------------- | ------------------------------------------------------ | | **PostgreSQL** | Persistent application and domain data | | **Redis** | Cache and asynchronous task broker | | **Celery** | Background processing | | **Audit** | System and application activity logging | | **Policy Engine** | Centralized authorization and access policies | | **Mailer** | Application email delivery and email-related workflows | | **Signals** | Event-driven application behavior | | **AuthX** | Identity authority for authentication-related flows | | **Generic Issue Tracker** | Reusable issue/helpdesk functionality | | **API Documentation** | Swagger / Redoc and API documentation infrastructure | --- ## **6. Generic Issue Tracker Integration** DjangoPlay integrates the reusable **Generic Issue Tracker** rather than maintaining a completely separate issue-management implementation inside the host application. The integration is located under the DjangoPlay integrations layer and connects DjangoPlay's helpdesk/issue workflows with the reusable tracker. ```mermaid flowchart TD DJANGO["DjangoPlay"] DJANGO --> HELP["Helpdesk / Issue UI"] DJANGO --> ADAPTER["Issue Tracker Integration"] ADAPTER --> GIT["Generic Issue Tracker"] GIT --> ISSUE_DB["Issue Tracker Models"] GIT --> API["DRF API"] GIT --> SIGNALS["Issue Events / Signals"] DJANGO --> ACCESS["DjangoPlay Access Control"] ACCESS --> ADAPTER classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b classDef integration fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444 classDef external fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91 class DJANGO app class HELP,ADAPTER,ACCESS integration class GIT,ISSUE_DB,API,SIGNALS external ``` The Generic Issue Tracker is a reusable Django package. DjangoPlay supplies its integration, access-control decisions, UI, and host-specific workflows. This keeps issue tracking functionality reusable independently of the DjangoPlay host application. --- ## **7. External Services** DjangoPlay communicates with external services where required by application features. | External Service | Usage | | ------------------------- | ----------------------------------------------------------- | | **AuthX** | Identity and authentication service | | **SMTP / Email Provider** | Application email delivery | | **Cloudflare DNS** | DNS and domain traffic management | | **Cloudflare Pages** | Static website and documentation hosting | | **Cloudflare R2** | Object storage for supported asset/reference-data workflows | | **Cloudflare Turnstile** | Optional bot and abuse protection | | **AI Providers** | AI inference when AI features are configured | | **External APIs** | Application-specific integrations | External integrations are kept behind application services and dedicated integration components rather than scattering provider-specific logic throughout views. --- ## **8. Static Assets and CDN Architecture** DjangoPlay supports Cloudflare-based delivery for static frontend assets. The application can build frontend assets locally and, where the deployment workflow requires it, publish them to Cloudflare R2. ```text Frontend Source │ ▼ Frontend Build │ ▼ dist / assets / vendor │ ▼ Cloudflare R2 │ ▼ CDN / Edge Delivery │ ▼ Browser ``` Local development does not require the CDN path. The development configuration can serve the generated frontend assets directly. The CDN/object-storage workflow is therefore an infrastructure capability rather than a prerequisite for normal local Django development. --- ## **9. Background Processing Infrastructure** DjangoPlay uses Celery for operations that should not block the HTTP request cycle. ```mermaid flowchart LR REQUEST["DjangoPlay Request"] REQUEST --> SERVICE["Service Layer"] SERVICE --> TASK["Celery Task"] TASK --> REDIS["Redis
Broker"] REDIS --> WORKER["Celery Worker"] WORKER --> DB["PostgreSQL"] WORKER --> EMAIL["Email Provider"] WORKER --> API["External APIs"] classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b classDef infra fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444 classDef external fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91 class REQUEST,SERVICE,TASK,WORKER app class REDIS,DB infra class EMAIL,API external ``` Typical asynchronous operations include: * Email delivery * Long-running processing * External service calls * Synchronization operations * Other work that should execute outside the request/response cycle Redis acts as the Celery broker and also provides application caching. --- ## **10. Database Infrastructure** PostgreSQL is the primary persistent database for DjangoPlay. The application follows a shared-database modular-monolith model: ```text PostgreSQL │ ┌────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ Identity Business Infrastructure Domains Domains Data ``` Individual Django apps own their domain models while using the same PostgreSQL deployment. Database performance is therefore an important consideration as the system grows. Indexing, query optimization, connection management, and appropriate resource sizing should be considered before introducing additional database topology. --- ## **11. Redis Infrastructure** Redis currently serves two primary roles: 1. **Application cache** 2. **Celery message broker** ```text DjangoPlay │ ├──────────────► Redis ◄────────────── Celery Worker │ │ │ ├── Cache │ └── Task Broker │ └──────────────► PostgreSQL ``` Redis is not the system of record. Persistent business and application data remains in PostgreSQL. --- ## **12. Authentication Infrastructure** AuthX is deployed as part of the production runtime and provides the identity authority for DjangoPlay authentication flows. ```mermaid flowchart LR USER["User / Browser"] USER --> DJANGO["DjangoPlay"] DJANGO --> AUTHX["AuthX
Identity Service"] AUTHX --> IDENTITY["Identity Data"] DJANGO --> SESSION["DjangoPlay Session / Application Context"] classDef user fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b classDef identity fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c class USER user class DJANGO,SESSION app class AUTHX,IDENTITY identity ``` AuthX is therefore both: * a **runtime infrastructure component**, because it runs as a service in the production environment; and * an **application integration**, because DjangoPlay communicates with it for identity-related operations. The detailed authentication architecture is documented separately. --- ## **13. Multi-Environment Support** DjangoPlay separates environment-specific settings through dedicated settings modules. | Settings Module | Environment | | ---------------------------- | ----------------- | | `paystream.settings.dev` | Local development | | `paystream.settings.staging` | Staging | | `paystream.settings.prod` | Production | Environment-specific configuration is supplied through the DjangoPlay configuration files rather than hard-coded into application code. Detailed configuration requirements are documented separately in the environment configuration reference. --- ## **14. Production Components** | Component | Role | | --------------------- | ----------------------------------------------------------- | | Cloudflare DNS | DNS and public traffic entry | | Cloudflare Pages | Static portfolio and documentation hosting | | GCP e2-micro VM | DjangoPlay production runtime | | Nginx | Reverse proxy and TLS/web server | | Gunicorn | Django WSGI application server | | DjangoPlay | Main application | | Celery | Background task processing | | Redis | Cache and Celery broker | | PostgreSQL | Primary persistent database | | AuthX | Identity service | | Generic Issue Tracker | Reusable issue/helpdesk capability | | Cloudflare R2 | Object storage and supported asset/reference-data workflows | | Cloudflare Turnstile | Optional bot/abuse protection | | SMTP / Email Provider | Application email delivery | | AI Providers | Optional AI inference services | | External APIs | Application integrations | --- ## **15. Operational Constraints** The current production host is intentionally small. The GCP e2-micro deployment prioritizes: * Low infrastructure cost * Operational simplicity * Straightforward deployment * Minimal infrastructure overhead * A single manageable production runtime The architecture should therefore not be interpreted as a large-scale distributed deployment. Scaling decisions should be driven by actual workload, resource utilization, database pressure, background-task volume, and availability requirements. --- ## **16. Scaling Direction** The current architecture can evolve without immediately converting the application into microservices. The preferred progression is: ```text Current │ ▼ Single GCP VM │ ├── Nginx ├── Django / Gunicorn ├── Celery ├── Redis └── AuthX │ ▼ Vertical Scaling │ ▼ Separate Runtime Components │ ├── Application nodes ├── Worker nodes ├── Managed PostgreSQL └── Managed Redis │ ▼ Horizontal Application Scaling ``` The modular-monolith architecture allows infrastructure scaling to occur before a decision is made to split individual domains into independent services. Microservices should therefore be considered an eventual option rather than a current infrastructure requirement. --- ## **17. Infrastructure Architecture Principles** | Principle | Description | | ---------------------------------- | ----------------------------------------------------------------------------- | | **Operational Simplicity** | Keep the production footprint small and manageable | | **Modular Application** | Maintain clear domain boundaries inside the monolith | | **Stateless Application Layer** | Keep application processes suitable for future horizontal scaling | | **Externalized Configuration** | Keep environment-specific configuration outside application code | | **Persistent Data in PostgreSQL** | PostgreSQL remains the primary system of record | | **Redis for Ephemeral/Async Work** | Use Redis for caching and task messaging rather than persistent business data | | **Asynchronous Processing** | Move suitable long-running work to Celery | | **Dedicated Identity Service** | Keep identity responsibility with AuthX | | **Integration Isolation** | Keep external provider logic behind integration boundaries | | **CDN/Edge Delivery** | Use Cloudflare where static and edge delivery provides value | | **Incremental Scaling** | Scale infrastructure according to measured requirements | --- ## **18. Summary** DjangoPlay currently operates as a **modular monolith on a small GCP production VM**, fronted by Cloudflare and Nginx. The production runtime consists primarily of: ```text Cloudflare │ ▼ Nginx │ ▼ Gunicorn │ ▼ DjangoPlay ├── PostgreSQL ├── Redis ├── Celery └── AuthX ``` The surrounding infrastructure provides: * Cloudflare Pages for the portfolio and documentation sites * Cloudflare R2 for supported object-storage workflows * Cloudflare Turnstile for optional abuse protection * SMTP/email services for application communication * AI providers and external APIs for optional application capabilities * Generic Issue Tracker for reusable issue/helpdesk functionality The architecture deliberately favors **simplicity today with clear paths for scaling tomorrow** rather than introducing distributed infrastructure before it is required.