# freedy-fr/ci-p5-magnaplate architecture

> Architecture diagram of the GitHub repository freedy-fr/ci-p5-magnaplate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/freedy-fr/ci-p5-magnaplate
- Repository: https://github.com/freedy-fr/ci-p5-magnaplate

## Overview

##### Project Type and Purpose
- This is a monolithic full-stack e-commerce web application built with Django (Python) that lets customers browse and purchase magnetic posters.
- Major concerns: user-facing storefront (products, cart, checkout, profiles, favorites), admin/Site-Management, payment integration (Stripe), file storage (AWS S3), and relational data (PostgreSQL).

##### File Structure Highlights
- Top-level Django project: manage.py, magnaplate/ (settings, URLs, WSGI/ASGI).
- Apps by feature: cart, checkout, favorites, footer, home, products, profiles (+ custom_storages, templates for allauth).
- Static & media: local static/, staticfiles/ (collected), media/ (user uploads).
- Dev/deploy: .devcontainer/, docker-compose.yml, Procfile, gitpod.yml.
- Configuration: requirements.txt, package-lock.json, robots.txt, sitemap.xml.

##### Key Architectural Patterns
- MVC: Django views ↔ templates (UI) ↔ models (DB).
- Modular app-per-feature for separation of concerns.
- Third-party integrations:
- Stripe for payments/webhooks
- AWS S3 via django-storages for static/media
- ElephantSQL (PostgreSQL) via dj-database-url
- Allauth for authentication
- Easy Thumbnails, Crispy Forms, Widget Tweaks

##### Main Components
A. Clients (Web Browser / Mobile)
B. CDN / AWS S3
- StaticAssets (CSS/JS/images)
- MediaAssets (product images, user uploads)
C. Heroku Router & Dyno
- Gunicorn WSGI server hosting Django app
- Docker container (optional) via .devcontainer
D. Django Application
- URLs & Views (cart, checkout, products, profiles, admin)
- Templates (Django + allauth)
- Business Logic (signals, context_processors, management commands)
- Custom Storage backends (custom_storages.py)
E. Database Layer
- PostgreSQL (ElephantSQL)
- Models: Order, OrderLineItem, Product, Category, Collection, Creator, UserProfile, Favorites, Newsletter, Carousel, SupportInquiry
F. External Services
- Stripe API & Webhooks
- Email (SMTP via Django)
- Google Fonts / FontAwesome / fslightbox (CDN)

##### Relationships & Data Flow
1. Client → DNS → Heroku Router → Gunicorn
2. Gunicorn → Django URL dispatcher → appropriate app-view
3. View ↔ Database queries (PostgreSQL)
4. View ↔ AWS S3 for file/media operations
5. Checkout View → Stripe API for PaymentIntent → Stripe Webhook → webhook_handler updates Order
6. Email notifications sent via SMTP or managed via Django’s EmailBackend
7. Admin users ↔ Django Admin → Database

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Devices"
        direction TB
        Browser["Web Browser / Mobile"]:::client
    end

    %% Dev & Deployment Layer
    subgraph "Dev & Deployment" 
        direction TB
        DevContainer[".devcontainer/"]:::dev
        DockerCompose["docker-compose.yml"]:::dev
        Procfile["Procfile"]:::dev
        Gitpod[".gitpod.yml"]:::dev
        click DevContainer "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/.devcontainer/"
        click DockerCompose "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/docker-compose.yml"
        click Procfile "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/Procfile"
        click Gitpod "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/.gitpod.yml"
    end

    %% CDN & Storage Layer
    subgraph "CDN & File Storage"
        direction TB
        StaticAssets["AWS S3 Static Bucket"]:::storage
        MediaAssets["AWS S3 Media Bucket"]:::storage
    end

    %% Backend / Django Layer
    subgraph "Backend / Django"
        direction TB
        HerokuRouter["Heroku Router & Dyno"]:::server
        Gunicorn["Gunicorn WSGI Server"]:::server
        DjangoProject["Django Project\n(magnaplate)"]:::backend
        manage["manage.py"]:::backend
        settings["magnaplate/settings.py"]:::backend
        urls["magnaplate/urls.py"]:::backend
        wsgi["magnaplate/wsgi.py"]:::backend
        asgi["magnaplate/asgi.py"]:::backend
        click manage "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/manage.py"
        click settings "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/magnaplate/settings.py"
        click urls "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/magnaplate/urls.py"
        click wsgi "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/magnaplate/wsgi.py"
        click asgi "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/magnaplate/asgi.py"

        subgraph "Apps"
            direction TB
            ProductsApp["Products App"]:::backend
            CartApp["Cart App"]:::backend
            CheckoutApp["Checkout & Payment App"]:::backend
            ProfilesApp["Profiles & Site Management App"]:::backend
            FavoritesApp["Favorites App"]:::backend
            HomeApp["Home Carousel & Landing Page App"]:::backend
            FooterApp["Footer & Customer Management App"]:::backend
            click ProductsApp "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/products/"
            click CartApp "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/cart/"
            click CheckoutApp "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/checkout/"
            click ProfilesApp "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/profiles/"
            click FavoritesApp "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/favorites/"
            click HomeApp "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/home/"
            click FooterApp "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/footer/"
        end

        subgraph "Templates & Auth"
            direction TB
            BaseTemplates["templates/base.html,\n404.html"]:::backend
            AllauthTemplates["templates/allauth/"]:::backend
            click BaseTemplates "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/templates/base.html"
            click AllauthTemplates "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/templates/allauth/"
        end

        subgraph "Business Logic"
            direction TB
            Signals["checkout/signals.py"]:::backend
            Contexts["cart/contexts.py\nproducts/context_processors.py"]:::backend
            Thumbnails["products/management/commands/generate_thumbnails.py"]:::backend
            click Signals "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/checkout/signals.py"
            click Contexts "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/cart/contexts.py"
            click Thumbnails "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/products/management/commands/generate_thumbnails.py"
        end

        subgraph "Payment Integration"
            direction TB
            StripeFrontend["static/checkout/js/stripe_elements.js"]:::frontend
            WebhookHandler["checkout/webhook_handler.py,\ncheckout/webhooks.py"]:::backend
            click StripeFrontend "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/static/checkout/js/stripe_elements.js"
            click WebhookHandler "https://github.com/freedy-fr/ci-p5-magnaplate/blob/main/checkout/webhook_handler.py"
        end
    end

    %% Persistence Layer
    subgraph "Persistence"
        direction TB
        Postgres["PostgreSQL\n(ElephantSQL)"]:::database
        DBModels["Django Models\n(Order,Product,UserProfile,...)"]:::database
        Migrations["*/migrations/"]:::database
        click Migrations "https://github.com/freedy-fr/ci-p5-magnaplate/tree/main/checkout/migrations/"
    end

    %% External Integrations
    subgraph "External Services"
        direction TB
        StripeAPI["Stripe API"]:::external
        SMTP["SMTP Email Service"]:::external
        CDNFonts["Google Fonts / FontAwesome CDN"]:::external
    end

    %% Connections
    Browser -->|"DNS → HTTPS"| HerokuRouter
    Browser -->|"GET Static"| StaticAssets
    Browser -->|"GET Media"| MediaAssets

    HerokuRouter -->|"HTTP"| Gunicorn
    Gunicorn -->|"WSGI"| DjangoProject

    DjangoProject -->|"URL Dispatch"| ProductsApp
    DjangoProject -->|"URL Dispatch"| CartApp
    DjangoProject -->|"URL Dispatch"| CheckoutApp
    DjangoProject -->|"URL Dispatch"| ProfilesApp
    DjangoProject -->|"URL Dispatch"| FavoritesApp
    DjangoProject -->|"URL Dispatch"| HomeApp
    DjangoProject -->|"URL Dispatch"| FooterApp

    CheckoutApp -->|"POST PaymentIntent"| StripeAPI
    StripeAPI -->|"Webhook POST"| WebhookHandler
    WebhookHandler -->|"Update Order"| DBModels

    ProductsApp -->|"SQL"| Postgres
    CartApp -->|"SQL"| Postgres
    ProfilesApp -->|"SQL"| Postgres
    FavoritesApp -->|"SQL"| Postgres
    HomeApp -->|"SQL"| Postgres
    FooterApp -->|"SQL"| Postgres

    CheckoutApp -->|"SQL"| Postgres

    DjangoProject -->|"S3 PUT/GET"| StaticAssets
    DjangoProject -->|"S3 PUT/GET"| MediaAssets

    DjangoProject -->|"SMTP"| SMTP

    Browser -->|"Load Fonts"| CDNFonts

    %% Dev & Deployment connections
    DevContainer --> DockerCompose
    DockerCompose --> HerokuRouter
    Procfile --> HerokuRouter
    Gitpod --> HerokuRouter

    %% Styles
    classDef client fill:#cccccc,stroke:#333,stroke-width:1px
    classDef frontend fill:#a2cffe,stroke:#333,stroke-width:1px
    classDef backend fill:#b2d8b2,stroke:#333,stroke-width:1px
    classDef server fill:#8fd6a2,stroke:#333,stroke-width:1px
    classDef storage fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef database fill:#99ccff,stroke:#333,stroke-width:1px
    classDef external fill:#d5b3ff,stroke:#333,stroke-width:1px
    classDef dev fill:#eeeeee,stroke:#333,stroke-width:1px
```
