# jbocciadev/pp5-crafty architecture

> Architecture diagram of the GitHub repository jbocciadev/pp5-crafty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jbocciadev/pp5-crafty
- Repository: https://github.com/jbocciadev/pp5-crafty

## Overview

1. **Overall shape**
   Crafty is a Django 3.2 monolith built around server-rendered pages, not a separate frontend/backend split. The project is divided into feature apps, each owning its own models, views, forms, URLs, templates, and tests.

2. **Request routing**
   The `crafty/urls.py` project router delegates to six main domains: `home`, `products`, `bag`, `checkout`, `profiles`, and `contact`. This is the primary architectural boundary for user-facing functionality.

3. **Core domain: product catalog**
   The `products` app is the catalog subsystem. It models categories, age groups, topics, products, and reviews. It also contains product management flows such as add/edit product pages, product detail pages, and review submission/editing. A custom widget and template tags support richer form rendering and rating display.

4. **Cart subsystem**
   The `bag` app is a session-backed shopping cart. It is responsible for add/update/remove item actions, bag totals, and the checkout entry point. Its template tags and partial templates are used to render item summaries consistently across product and bag pages.

5. **Checkout and payment boundary**
   The `checkout` app owns purchase finalization. It contains the `Order` and order line item models, checkout form, checkout page, success page, and Stripe integration. The JavaScript in `checkout/static/checkout/js/stripe_elements.js` drives card collection, while `webhooks.py` and `webhook_handler.py` handle payment event reconciliation on the server side. This app is the boundary between the site and the external payment processor.

6. **User accounts and profiles**
   Authentication is handled through Django allauth, with custom templates overriding the default auth UI. The `profiles` app extends the built-in user with a `UserProfile` model for delivery/contact details and exposes a profile page with order history and profile management forms. This app is the user account boundary for personal data and post-purchase history.

7. **Contact and newsletter**
   The `contact` app manages customer contact submissions and newsletter subscribers. It includes an unsubscribe flow and likely sends notification emails to the support mailbox and confirmation emails to the user. This is separate from checkout communications and acts as the site’s general inbound communication channel.

8. **Public pages and shared site shell**
   The `home` app provides the landing page, while the global `templates/` directory supplies shared layout and reusable UI fragments: main navigation, desktop/mobile footers, modal dialogs, and toast notifications. These shared templates are the presentation layer used across all apps.

9. **Data model relationships**
   The system centers on a few key relational flows: users own profiles; products belong to catalog taxonomies; reviews attach users to products; orders own line items; order history is surfaced back into profiles. This creates a clean separation between browse, cart, and fulfillment data.

10. **Static and media handling**
   Static CSS/JS lives under each app or in the global `static/` directory. Media assets, including product images and site imagery, are stored separately and the repo includes `custom_storages.py`, indicating custom storage configuration for production media/static hosting.

11. **Infrastructure and deployment**
   The app is deployed on Heroku with Gunicorn as the WSGI server. Production data is stored in PostgreSQL via ElephantSQL, and the app uses environment variables for secrets and service credentials. The README and config files indicate AWS S3 integration for static/media storage.

12. **External service integrations**
   The two main external integrations are Stripe for payments and email delivery for confirmations/notifications. Django allauth provides account management, while Stripe webhooks provide a trusted asynchronous payment confirmation path after checkout submission.

13. **Operational and cross-cutting concerns**
   The repo includes custom error pages, sitemap and robots files for SEO, and Django admin customizations for staff operations. Migrations are present for each app, and the included tests show that each subsystem is meant to be validated independently.

14. **In practical diagram terms**
   A useful architecture diagram would show: browser requests into Django; Django dispatching into feature apps; shared templates/static supporting all apps; checkout branching out to Stripe and email; and persistence flowing into PostgreSQL and AWS-backed media/static storage. The main trust boundary is the checkout/payment path, followed by auth/profile data and contact/newsletter messaging.

Main entry points: [`crafty/urls.py`](https://github.com/jbocciadev/pp5-crafty/blob/main/crafty/urls.py) (Project router), [`checkout/views.py`](https://github.com/jbocciadev/pp5-crafty/blob/main/checkout/views.py) (Checkout), [`products/views.py`](https://github.com/jbocciadev/pp5-crafty/blob/main/products/views.py) (Catalog), [`profiles/views.py`](https://github.com/jbocciadev/pp5-crafty/blob/main/profiles/views.py) (Profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core apps"]
  node_crafty_urls["Project router<br/>django urls<br/>[urls.py]"]
  node_home_app["Home<br/>landing app<br/>[views.py]"]
  node_products_app["Catalog<br/>[views.py]"]
  node_bag_app["Bag<br/>cart app<br/>[views.py]"]
  node_checkout_app["Checkout<br/>payment app<br/>[views.py]"]
  node_profiles_app["Profiles<br/>account app<br/>[views.py]"]
  node_contact_app["Contact<br/>[views.py]"]
  node_product_models[("Catalog data<br/>models<br/>[models.py]")]
  node_product_forms["Product forms<br/>forms and widgets<br/>[forms.py]"]
  node_bag_contexts["Bag context<br/>cart helpers<br/>[contexts.py]"]
  node_order_models[("Orders<br/>checkout models<br/>[models.py]")]
  node_checkout_forms["Checkout form<br/>payment form<br/>[forms.py]"]
  node_webhooks_handler["Webhooks<br/>payment webhook<br/>[webhooks.py]"]
  node_profile_models[("User profile<br/>profile model<br/>[models.py]")]
  node_contact_models[("Subscribers<br/>contact models<br/>[models.py]")]
end

subgraph group_shared["Shared UI"]
  node_site_shell["Site shell<br/>shared templates<br/>[base.html]"]
  node_allauth_templates["Auth UI<br/>auth templates<br/>[login.html]"]
  node_shared_static["Shared static<br/>static assets<br/>[base.css]"]
end

subgraph group_integrations["Integrations"]
  node_stripe(("Stripe<br/>payment gateway"))
  node_email(("Email<br/>mail delivery"))
  node_postgresql[("PostgreSQL<br/>database")]
  node_storage[("S3 storage<br/>object storage<br/>[custom_storages.py]")]
end

subgraph group_ops["Ops"]
  node_heroku["Heroku<br/>deployment"]
  node_env_config["Runtime config<br/>settings<br/>[settings.py]"]
end

node_crafty_urls -->|"routes"| node_home_app
node_crafty_urls -->|"routes"| node_products_app
node_crafty_urls -->|"routes"| node_bag_app
node_crafty_urls -->|"routes"| node_checkout_app
node_crafty_urls -->|"routes"| node_profiles_app
node_crafty_urls -->|"routes"| node_contact_app
node_home_app -->|"renders"| node_site_shell
node_products_app -->|"reads/writes"| node_product_models
node_products_app -->|"uses"| node_product_forms
node_products_app -->|"renders"| node_site_shell
node_bag_app -->|"computes"| node_bag_contexts
node_bag_app -->|"renders"| node_site_shell
node_checkout_app -->|"persists"| node_order_models
node_checkout_app -->|"uses"| node_checkout_forms
node_checkout_app -->|"charges"| node_stripe
node_webhooks_handler -->|"receives events"| node_stripe
node_webhooks_handler -->|"updates"| node_order_models
node_checkout_app -->|"sends"| node_email
node_profiles_app -->|"reads/writes"| node_profile_models
node_profiles_app -->|"reads"| node_order_models
node_contact_app -->|"persists"| node_contact_models
node_contact_app -->|"sends"| node_email
node_allauth_templates -.->|"supports auth"| node_profiles_app
node_site_shell -->|"loads"| node_shared_static
node_env_config -.->|"configures"| node_stripe
node_env_config -.->|"configures"| node_postgresql
node_env_config -.->|"configures"| node_storage
node_heroku -.->|"uses"| node_env_config
node_checkout_app -->|"stores"| node_postgresql
node_products_app -->|"stores"| node_postgresql
node_profiles_app -->|"stores"| node_postgresql
node_contact_app -->|"stores"| node_postgresql
node_storage -.->|"serves"| node_shared_static

click node_crafty_urls "https://github.com/jbocciadev/pp5-crafty/blob/main/crafty/urls.py"
click node_home_app "https://github.com/jbocciadev/pp5-crafty/blob/main/home/views.py"
click node_products_app "https://github.com/jbocciadev/pp5-crafty/blob/main/products/views.py"
click node_bag_app "https://github.com/jbocciadev/pp5-crafty/blob/main/bag/views.py"
click node_checkout_app "https://github.com/jbocciadev/pp5-crafty/blob/main/checkout/views.py"
click node_profiles_app "https://github.com/jbocciadev/pp5-crafty/blob/main/profiles/views.py"
click node_contact_app "https://github.com/jbocciadev/pp5-crafty/blob/main/contact/views.py"
click node_product_models "https://github.com/jbocciadev/pp5-crafty/blob/main/products/models.py"
click node_product_forms "https://github.com/jbocciadev/pp5-crafty/blob/main/products/forms.py"
click node_bag_contexts "https://github.com/jbocciadev/pp5-crafty/blob/main/bag/contexts.py"
click node_order_models "https://github.com/jbocciadev/pp5-crafty/blob/main/checkout/models.py"
click node_checkout_forms "https://github.com/jbocciadev/pp5-crafty/blob/main/checkout/forms.py"
click node_webhooks_handler "https://github.com/jbocciadev/pp5-crafty/blob/main/checkout/webhooks.py"
click node_profile_models "https://github.com/jbocciadev/pp5-crafty/blob/main/profiles/models.py"
click node_contact_models "https://github.com/jbocciadev/pp5-crafty/blob/main/contact/models.py"
click node_site_shell "https://github.com/jbocciadev/pp5-crafty/blob/main/templates/base.html"
click node_allauth_templates "https://github.com/jbocciadev/pp5-crafty/blob/main/templates/allauth/account/login.html"
click node_shared_static "https://github.com/jbocciadev/pp5-crafty/blob/main/static/css/base.css"
click node_storage "https://github.com/jbocciadev/pp5-crafty/blob/main/custom_storages.py"
click node_heroku "https://github.com/jbocciadev/pp5-crafty/tree/main/Procfile"
click node_env_config "https://github.com/jbocciadev/pp5-crafty/blob/main/crafty/settings.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_crafty_urls,node_home_app,node_products_app,node_bag_app,node_checkout_app,node_profiles_app,node_contact_app,node_product_models,node_product_forms,node_bag_contexts,node_order_models,node_checkout_forms,node_webhooks_handler,node_profile_models,node_contact_models toneBlue
class node_site_shell,node_allauth_templates,node_shared_static toneAmber
class node_stripe,node_email,node_postgresql,node_storage toneMint
class node_heroku,node_env_config toneRose
```

## Components

### Core apps

Feature apps behind the main site routes

- [Project router](https://github.com/jbocciadev/pp5-crafty/blob/main/crafty/urls.py): django urls · Delegates site traffic to feature apps · `crafty/urls.py`
- [Home](https://github.com/jbocciadev/pp5-crafty/blob/main/home/views.py): landing app · Public landing page and home route · `home/views.py`
- [Catalog](https://github.com/jbocciadev/pp5-crafty/blob/main/products/views.py): catalog app · Products, categories, reviews, and product management flows · `products/views.py`
- [Bag](https://github.com/jbocciadev/pp5-crafty/blob/main/bag/views.py): cart app · Session-backed shopping cart and bag actions · `bag/views.py`
- [Checkout](https://github.com/jbocciadev/pp5-crafty/blob/main/checkout/views.py): payment app · Order finalization and payment processing boundary · `checkout/views.py`
- [Profiles](https://github.com/jbocciadev/pp5-crafty/blob/main/profiles/views.py): account app · User profile, delivery details, and order history · `profiles/views.py`
- [Contact](https://github.com/jbocciadev/pp5-crafty/blob/main/contact/views.py): contact app · Contact submissions and newsletter unsubscribe flow · `contact/views.py`
- [Catalog data](https://github.com/jbocciadev/pp5-crafty/blob/main/products/models.py): models · Categories, age groups, topics, products, and reviews · `products/models.py`
- [Product forms](https://github.com/jbocciadev/pp5-crafty/blob/main/products/forms.py): forms and widgets · Admin/product edit forms and custom file input widget · `products/forms.py`
- [Bag context](https://github.com/jbocciadev/pp5-crafty/blob/main/bag/contexts.py): cart helpers · Cart summary data injected into templates · `bag/contexts.py`
- [Orders](https://github.com/jbocciadev/pp5-crafty/blob/main/checkout/models.py): checkout models · Order and order line items persisted at checkout · `checkout/models.py`
- [Checkout form](https://github.com/jbocciadev/pp5-crafty/blob/main/checkout/forms.py): payment form · Checkout page form used to collect order details · `checkout/forms.py`
- [Webhooks](https://github.com/jbocciadev/pp5-crafty/blob/main/checkout/webhooks.py): payment webhook · Stripe event reconciliation and fulfillment updates · `checkout/webhooks.py`
- [User profile](https://github.com/jbocciadev/pp5-crafty/blob/main/profiles/models.py): profile model · Extended user record for delivery and contact data · `profiles/models.py`
- [Subscribers](https://github.com/jbocciadev/pp5-crafty/blob/main/contact/models.py): contact models · Contact submissions and newsletter subscriber records · `contact/models.py`

### Shared UI

Global templates and static assets used across apps

- [Site shell](https://github.com/jbocciadev/pp5-crafty/blob/main/templates/base.html): shared templates · Global layout, nav, footers, modals, toasts, and error pages · `templates/base.html`
- [Auth UI](https://github.com/jbocciadev/pp5-crafty/blob/main/templates/allauth/account/login.html): auth templates · Custom allauth login, signup, reset, and email templates · `templates/allauth/account/login.html`
- [Shared static](https://github.com/jbocciadev/pp5-crafty/blob/main/static/css/base.css): static assets · Global CSS, favicon, and site-wide styling assets · `static/css/base.css`

### Integrations

External services and boundaries

- **Stripe**: payment gateway · External card payment processor
- **Email**: mail delivery · Outbound notification and confirmation delivery
- **PostgreSQL**: database · Primary relational persistence for site data
- [S3 storage](https://github.com/jbocciadev/pp5-crafty/blob/main/custom_storages.py): object storage · External media and static asset storage · `custom_storages.py`

### Ops

Deployment and environment configuration

- [Heroku](https://github.com/jbocciadev/pp5-crafty/tree/main/Procfile): deployment · Runtime and deployment environment · `Procfile`
- [Runtime config](https://github.com/jbocciadev/pp5-crafty/blob/main/crafty/settings.py): settings · Environment-driven secrets and service configuration · `crafty/settings.py`

## Connections

- Project router → Home: routes · Dispatches the home route
- Project router → Catalog: routes · Dispatches catalog URLs
- Project router → Bag: routes · Dispatches bag URLs
- Project router → Checkout: routes · Dispatches checkout URLs
- Project router → Profiles: routes · Dispatches profile URLs
- Project router → Contact: routes · Dispatches contact URLs
- Home → Site shell: renders · Uses shared site chrome and layout
- Catalog → Catalog data: reads/writes · Catalog and review data access
- Catalog → Product forms: uses · Product creation and edit flows
- Catalog → Site shell: renders · Uses global templates and includes
- Bag → Bag context: computes · Builds cart summary context for pages
- Bag → Site shell: renders · Uses shared page chrome and partials
- Checkout → Orders: persists · Creates orders and line items
- Checkout → Checkout form: uses · Collects checkout details
- Checkout → Stripe: charges · Starts payment flow with Stripe
- Webhooks → Stripe: receives events · Handles asynchronous payment confirmation
- Webhooks → Orders: updates · Reconciles order state after payment events
- Checkout → Email: sends · Sends confirmation emails
- Profiles → User profile: reads/writes · Stores delivery and contact details
- Profiles → Orders: reads · Displays user order history
- Contact → Subscribers: persists · Stores contact submissions and subscribers
- Contact → Email: sends · Notifies support and confirms subscriptions
- Auth UI → Profiles: supports auth · Customizes account and signup experience
- Site shell → Shared static: loads · Shared styles and site assets
- Runtime config → Stripe: configures · Supplies API keys and service settings
- Runtime config → PostgreSQL: configures · Database connection settings
- Runtime config → S3 storage: configures · Media and static storage configuration
- Heroku → Runtime config: uses · Production runtime configuration
- Checkout → PostgreSQL: stores · Order and checkout data
- Catalog → PostgreSQL: stores · Catalog and review data
- Profiles → PostgreSQL: stores · Profile data
- Contact → PostgreSQL: stores · Contact and subscriber data
- S3 storage → Shared static: serves · Hosts media and static assets