# paulocoutinhox/pyaa architecture

> Architecture diagram of the GitHub repository paulocoutinhox/pyaa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paulocoutinhox/pyaa
- Repository: https://github.com/paulocoutinhox/pyaa

## Overview

##### Project type and purpose
- This is a full-stack, monolithic Django application template (“PyAA – Python Advanced Application”) meant to bootstrap web sites, e-commerce platforms or SaaS products.
- Key features (from README): user & subscription management, credit & checkout system, banner & content management, multi-language, static content, admin reports, background queue (DjangoQ), cron jobs, Stripe & email integration, Docker support.

##### File structure
- Top-level “manage.py” and “pyaa/” folder define the Django project (settings/dev.py, settings/prod.py, urls.py, wsgi/asgi).
- “apps/” contains all domain apps (backup, banner, content, customer, gallery, language, newsletter, report, shop, site, system_log, user, web). Each app follows Django’s MVC (models, views, serializers, urls, migrations, tests).
- “templates/” & “apps/web/static/” contain the frontend layer (server-side templates, SASS/CSS, JS, images).
- Dockerfile(s), nginx.conf, and entrypoint scripts define containerized web and cron environments.
- “extras/production” and “docs/” cover deployment, database, queue, cron, Stripe, security, etc.

##### README for additional insights
- Technology stack: Python, Django, Django REST (serializers, API docs), DjangoQ (background queue), PostgreSQL/MySQL (DB), Stripe (payments), Recaptcha, uWSGI + Nginx, Docker.
- Architectural patterns: Monolithic MVC with clear app‐module separation; background workers & cron for async/periodic tasks; REST API endpoints; server‐side rendering with optional client‐side JS.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Browser / Mobile"]:::client
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        Nginx["Nginx Reverse Proxy"]:::infra
        DockerWeb["Dockerized Web Service"]:::infra
        DockerCron["Dockerized Cron Service"]:::infra
    end

    %% Application Layer
    subgraph "Django Project Core"
        manage("manage.py"):::app
        SettingsDev["Dev Settings"]:::app
        SettingsProd["Prod Settings"]:::app
        Router["URL Routing (pyaa/urls.py)"]:::app
        WSGI["WSGI App (pyaa/wsgi.py)"]:::app
        ASGI["ASGI App (pyaa/asgi.py)"]:::app
    end

    subgraph "Domain Apps"
        BackupApp["Backup App (apps/backup/)"]:::app
        BannerApp["Banner App (apps/banner/)"]:::app
        ContentApp["Content App (apps/content/)"]:::app
        CustomerApp["Customer App (apps/customer/)"]:::app
        GalleryApp["Gallery App (apps/gallery/)"]:::app
        LanguageApp["Language App (apps/language/)"]:::app
        NewsletterApp["Newsletter App (apps/newsletter/)"]:::app
        ReportApp["Reporting App (apps/report/)"]:::app
        ShopApp["Shop/E-Commerce App (apps/shop/)"]:::app
        StripeGateway["Stripe Gateway"]:::app
        SiteApp["Site Config App (apps/site/)"]:::app
        SystemLogApp["System Log App (apps/system_log/)"]:::app
        UserApp["User & Auth App (apps/user/)"]:::app
        WebApp["Web Frontend App (apps/web/)"]:::app
    end

    subgraph "Utilities"
        Mixins["Mixins (pyaa/mixins.py)"]:::app
        Utils["Utils (pyaa/utils/)"]:::app
        Helpers["Helpers (pyaa/helpers/)"]:::app
        EmailHelper["Email Helpers"]:::app
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["Database (PostgreSQL/MySQL)"]:::data
        Broker["Cache/Broker (Redis)"]:::data
        StaticStore["Static Asset Store (CDN/Nginx)"]:::data
    end

    %% Worker & Cron Layer
    subgraph "Worker Layer"
        Workers["DjangoQ Workers"]:::worker
        CronContainer["Cron Container"]:::worker
        ManagementCmds["Mgmt Commands"]:::worker
    end

    %% External Services
    subgraph "External Integrations"
        Stripe["Stripe API"]:::external
        SMTP["SMTP Email"]:::external
        Recaptcha["Recaptcha"]:::external
    end

    %% Flows
    Browser -->|HTTP/HTTPS| Nginx
    Browser -->|GET static assets| StaticStore
    Nginx -->|proxy to uWSGI| WSGI
    Nginx -->|serve cron| DockerCron
    DockerWeb -->|runs| WSGI
    DockerCron -->|executes| ManagementCmds
    ManagementCmds -->|commands| BackupApp
    ManagementCmds -->|commands| UserApp

    WSGI --> Router
    Router --> BackupApp
    Router --> BannerApp
    Router --> ContentApp
    Router --> CustomerApp
    Router --> GalleryApp
    Router --> LanguageApp
    Router --> NewsletterApp
    Router --> ReportApp
    Router --> ShopApp
    Router --> SiteApp
    Router --> SystemLogApp
    Router --> UserApp
    Router --> WebApp

    ShopApp --> StripeGateway
    StripeGateway -->|HTTPS| Stripe
    WebApp -->|renders templates| Router

    BackupApp --> DB
    BannerApp --> DB
    ContentApp --> DB
    CustomerApp --> DB
    GalleryApp --> DB
    LanguageApp --> DB
    NewsletterApp --> DB
    ReportApp --> DB
    ShopApp --> DB
    SiteApp --> DB
    SystemLogApp --> DB
    UserApp --> DB

    ShopApp -->|enqueue tasks| Broker
    BackupApp -->|enqueue tasks| Broker
    ReportApp -->|enqueue tasks| Broker

    Broker --> Workers
    Workers -->|process tasks| BackupApp
    Workers -->|process tasks| ReportApp
    Workers -->|send emails| EmailHelper
    Workers -->|run cron jobs| ManagementCmds

    Router -->|use mixins/utilities| Mixins
    Router -->|use utils/helpers| Utils
    Router -->|use helpers/email| EmailHelper

    UserApp -->|create admin| ManagementCmds

    Router --> SMTP
    Router --> Recaptcha

    %% Click Events
    click manage "https://github.com/paulocoutinhox/pyaa/blob/main/manage.py"
    click SettingsDev "https://github.com/paulocoutinhox/pyaa/blob/main/pyaa/settings/dev.py"
    click SettingsProd "https://github.com/paulocoutinhox/pyaa/blob/main/pyaa/settings/prod.py"
    click Router "https://github.com/paulocoutinhox/pyaa/blob/main/pyaa/urls.py"
    click WSGI "https://github.com/paulocoutinhox/pyaa/blob/main/pyaa/wsgi.py"
    click ASGI "https://github.com/paulocoutinhox/pyaa/blob/main/pyaa/asgi.py"
    click BackupApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/backup/"
    click BannerApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/banner/"
    click ContentApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/content/"
    click CustomerApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/customer/"
    click GalleryApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/gallery/"
    click LanguageApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/language/"
    click NewsletterApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/newsletter/"
    click ReportApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/report/"
    click ShopApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/shop/"
    click StripeGateway "https://github.com/paulocoutinhox/pyaa/blob/main/apps/shop/gateways/stripe.py"
    click SiteApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/site/"
    click SystemLogApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/system_log/"
    click UserApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/user/"
    click WebApp "https://github.com/paulocoutinhox/pyaa/tree/main/apps/web/"
    click Mixins "https://github.com/paulocoutinhox/pyaa/blob/main/pyaa/mixins.py"
    click Utils "https://github.com/paulocoutinhox/pyaa/tree/main/pyaa/utils/"
    click Helpers "https://github.com/paulocoutinhox/pyaa/tree/main/pyaa/helpers/"
    click EmailHelper "https://github.com/paulocoutinhox/pyaa/blob/main/pyaa/helpers/email.py"
    click DockerWeb "https://github.com/paulocoutinhox/pyaa/tree/main/Dockerfile"
    click Nginx "https://github.com/paulocoutinhox/pyaa/blob/main/nginx.conf"
    click DockerCron "https://github.com/paulocoutinhox/pyaa/blob/main/Dockerfile.cron"

    %% Styles
    classDef client fill:#ccf,stroke:#333
    classDef infra fill:#ddd,stroke:#333
    classDef app fill:#cfc,stroke:#333
    classDef data fill:#cff,stroke:#333
    classDef worker fill:#c9f,stroke:#333
    classDef external fill:#fc9,stroke:#333
```
