# aaron-pweb/pj-store-flask architecture

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

- Interactive diagram: https://gitdiagram.com/aaron-pweb/pj-store-flask
- Repository: https://github.com/aaron-pweb/pj-store-flask

## Overview

1. **Overall shape**
   This is a Flask monolith organized by feature blueprints rather than by technical layer. The app is split into `auth`, `main`, `products`, `orders`, `payments`, and `support`, with shared Flask extensions in `app/extensions.py` and a single startup path through `run.py`.

2. **Core request boundary**
   Each business area owns its own `routes.py`, and most also own their own `models.py`, `forms.py`, and template folder. That makes the architecture easy to diagram as a set of vertical slices: HTTP request in, blueprint route handler, model/form logic, database access, HTML response.

3. **Identity and access control**
   `app/auth` is the security and user-management boundary. It contains login/signup/profile flows, role-based dashboards, user/admin management, address book handling, and access-control decorators/constants. The presence of multiple dashboard templates shows that role determines both available actions and landing pages.

4. **Catalog and merchandising**
   `app/products` owns product lifecycle and browsing: catalog, product detail pages, product creation/editing, category management, variants, reviews, wishlist, and seller-facing product views. This subsystem is the source of product data used later by cart, checkout, and order views.

5. **Cart, orders, and fulfillment**
   `app/orders` handles the transactional side of the store: cart UI, checkout-address selection, order detail/history, and returns. It is the bridge between product selection and payment completion, and likely persists the order state that other roles inspect in their dashboards.

6. **Payments integration**
   `app/payments` is a thin boundary around Stripe-based checkout. Its separate routes and utility module suggest payment session creation/verification is isolated from order creation, with a payment success page kept in the top-level templates.

7. **Support/ticketing subsystem**
   `app/support` provides a separate support workflow with tickets, threaded messages, and support inbox views. This is operationally distinct from commerce: it likely reads user/order context but owns its own conversation data and staff-facing interface.

8. **Main/public entry point**
   `app/main` contains the public landing page and acts as the simplest unauthenticated entry route into the platform. This is the front door before users branch into auth, product browsing, or cart-related flows.

9. **Shared infrastructure**
   `app/extensions.py` indicates common Flask services are initialized centrally, likely including the database, login/session management, and form protection. The README confirms SQLAlchemy, Flask-Login, Flask-WTF/CSRF, and environment-driven config, so these are cross-cutting concerns rather than feature-local code.

10. **Templates and presentation**
   Templates are organized both globally (`app/templates`) and per blueprint. Global templates cover base layout, error pages, login/register, cart, and payment success, while feature templates stay close to their owning subsystem. This suggests server-rendered HTML is the primary UI delivery mechanism, with Bootstrap and a small amount of JS in `app/static/js/theme.js`.

11. **Data model boundaries**
   The models are split by domain: authentication/user entities, products/catalog entities, orders, and support tickets/messages. That separation implies each subsystem owns its own persistence model, with the order flow likely referencing products and users rather than sharing a large god-model.

12. **Bootstrap and operational setup**
   `create_super_admin.py` is an explicit provisioning script for initial platform administration, separate from runtime request handling. Together with `run.py`, it shows the repo has a clear distinction between startup/bootstrap operations and the live web application.

13. **Primary end-to-end flow**
   The main business path is: user authenticates → browses products → manages cart/order intent → selects address → pays via Stripe → receives order confirmation/history access. Side flows branch off for seller product management, admin/super-admin governance, and support ticket handling.

14. **Architecture summary for diagramming**
   A good diagram should show one Flask app at the center, shared infra beneath it, and six feature blueprints around it with their own routes/templates/models. The most important external dependency is Stripe; the most important internal boundaries are roles, catalog, order/payment transaction flow, and support.

Main entry points: [`app/__init__.py`](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/__init__.py) (App init), [`app/auth/routes.py`](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/auth/routes.py) (Auth routes), [`app/products/routes.py`](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/products/routes.py) (Products), [`app/orders/routes.py`](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/orders/routes.py) (Orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["Flask app"]
  node_node_app_init["App init<br/>app factory<br/>[__init__.py]"]
  node_node_extensions["Extensions<br/>shared services<br/>[extensions.py]"]
end

subgraph group_group_features["Feature blueprints"]
  node_node_main["Main<br/>public entry<br/>[routes.py]"]
  node_node_auth_routes["Auth routes<br/>identity boundary<br/>[routes.py]"]
  node_node_auth_models[("Auth models<br/>identity data<br/>[models.py]")]
  node_node_auth_forms["Auth forms<br/>identity forms<br/>[forms.py]"]
  node_node_auth_rules["Access rules<br/>authorization helpers<br/>[decorators.py]"]
  node_node_products_routes["Products<br/>catalog boundary<br/>[routes.py]"]
  node_node_products_models[("Product models<br/>catalog data<br/>[models.py]")]
  node_node_products_forms["Product forms<br/>catalog forms<br/>[forms.py]"]
  node_node_products_utils["Catalog utils<br/>catalog helpers<br/>[utils.py]"]
  node_node_orders_routes["Orders<br/>transaction boundary<br/>[routes.py]"]
  node_node_orders_models[("Order models<br/>transaction data<br/>[models.py]")]
  node_node_payments_routes["Payments<br/>stripe boundary<br/>[routes.py]"]
  node_node_payments_utils["Payment utils<br/>stripe helpers<br/>[utils.py]"]
  node_node_support_routes["Support<br/>ticketing boundary<br/>[routes.py]"]
  node_node_support_models[("Support models<br/>support data<br/>[models.py]")]
end

subgraph group_group_ui["Presentation"]
  node_node_base_tpl["Base layout<br/>shared templates<br/>[base.html]"]
  node_node_feature_tpls["Feature views<br/>feature templates"]
  node_node_theme_js["Theme JS<br/>browser script<br/>[theme.js]"]
end

subgraph group_group_bootstrap["Bootstrap"]
  node_node_run["run.py<br/>startup<br/>[run.py]"]
  node_node_super_admin["Admin seed<br/>provisioning script"]
end

node_node_run -->|"starts"| node_node_app_init
node_node_super_admin -.->|"seeds"| node_node_auth_models
node_node_app_init -->|"configures"| node_node_extensions
node_node_app_init -->|"registers"| node_node_main
node_node_app_init -->|"registers"| node_node_auth_routes
node_node_app_init -->|"registers"| node_node_products_routes
node_node_app_init -->|"registers"| node_node_orders_routes
node_node_app_init -->|"registers"| node_node_payments_routes
node_node_app_init -->|"registers"| node_node_support_routes
node_node_auth_routes -->|"reads/writes"| node_node_auth_models
node_node_auth_routes -->|"uses"| node_node_auth_forms
node_node_auth_routes -->|"guards"| node_node_auth_rules
node_node_products_routes -->|"reads/writes"| node_node_products_models
node_node_products_routes -->|"uses"| node_node_products_forms
node_node_products_routes -.->|"uses"| node_node_products_utils
node_node_orders_routes -->|"reads/writes"| node_node_orders_models
node_node_orders_routes -.->|"consumes"| node_node_products_models
node_node_payments_routes -->|"uses"| node_node_payments_utils
node_node_payments_routes -.->|"finalizes"| node_node_orders_models
node_node_support_routes -->|"reads/writes"| node_node_support_models
node_node_auth_routes -->|"renders"| node_node_base_tpl
node_node_products_routes -->|"renders"| node_node_feature_tpls
node_node_orders_routes -->|"renders"| node_node_feature_tpls
node_node_payments_routes -->|"renders"| node_node_feature_tpls
node_node_support_routes -->|"renders"| node_node_feature_tpls
node_node_app_init -.->|"serves"| node_node_theme_js
node_node_app_init -.->|"serves"| node_node_base_tpl

click node_node_run "https://github.com/aaron-pweb/pj-store-flask/blob/master/run.py"
click node_node_super_admin "https://github.com/aaron-pweb/pj-store-flask/blob/master/create_super_admin.py"
click node_node_app_init "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/__init__.py"
click node_node_extensions "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/extensions.py"
click node_node_main "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/main/routes.py"
click node_node_auth_routes "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/auth/routes.py"
click node_node_auth_models "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/auth/models.py"
click node_node_auth_forms "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/auth/forms.py"
click node_node_auth_rules "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/auth/decorators.py"
click node_node_products_routes "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/products/routes.py"
click node_node_products_models "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/products/models.py"
click node_node_products_forms "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/products/forms.py"
click node_node_products_utils "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/products/utils.py"
click node_node_orders_routes "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/orders/routes.py"
click node_node_orders_models "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/orders/models.py"
click node_node_payments_routes "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/payments/routes.py"
click node_node_payments_utils "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/payments/utils.py"
click node_node_support_routes "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/support/routes.py"
click node_node_support_models "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/support/models.py"
click node_node_base_tpl "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/templates/base.html"
click node_node_theme_js "https://github.com/aaron-pweb/pj-store-flask/blob/master/app/static/js/theme.js"

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_node_app_init,node_node_extensions toneBlue
class node_node_main,node_node_auth_routes,node_node_auth_models,node_node_auth_forms,node_node_auth_rules,node_node_products_routes,node_node_products_models,node_node_products_forms,node_node_products_utils,node_node_orders_routes,node_node_orders_models,node_node_payments_routes,node_node_payments_utils,node_node_support_routes,node_node_support_models toneAmber
class node_node_base_tpl,node_node_feature_tpls,node_node_theme_js toneMint
class node_node_run,node_node_super_admin toneRose
```

## Components

### Flask app

Application package and shared startup wiring.

- [App init](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/__init__.py): app factory · Creates and configures the Flask application package. · `app/__init__.py`
- [Extensions](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/extensions.py): shared services · Central Flask extension wiring such as database, auth, and CSRF. · `app/extensions.py`

### Feature blueprints

Business domains implemented as Flask blueprints.

- [Main](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/main/routes.py): public entry · Public landing and unauthenticated entry routes. · `app/main/routes.py`
- [Auth routes](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/auth/routes.py): identity boundary · Login, signup, profile, dashboards, and admin/user management flows. · `app/auth/routes.py`
- [Auth models](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/auth/models.py): identity data · Users, roles, addresses, and related security data. · `app/auth/models.py`
- [Auth forms](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/auth/forms.py): identity forms · Forms for login, signup, profile, and address workflows. · `app/auth/forms.py`
- [Access rules](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/auth/decorators.py): authorization helpers · Role constants and decorators for protected views. · `app/auth/decorators.py`
- [Products](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/products/routes.py): catalog boundary · Catalog browsing, product management, variants, reviews, and wishlist flows. · `app/products/routes.py`
- [Product models](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/products/models.py): catalog data · Product, category, variant, and review persistence. · `app/products/models.py`
- [Product forms](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/products/forms.py): catalog forms · Forms for product, category, review, and related editing flows. · `app/products/forms.py`
- [Catalog utils](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/products/utils.py): catalog helpers · Supporting logic for product-related operations. · `app/products/utils.py`
- [Orders](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/orders/routes.py): transaction boundary · Cart, checkout address selection, order detail/history, and returns. · `app/orders/routes.py`
- [Order models](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/orders/models.py): transaction data · Cart and order persistence used across purchase and fulfillment flows. · `app/orders/models.py`
- [Payments](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/payments/routes.py): stripe boundary · Checkout/payment session routes and success handling. · `app/payments/routes.py`
- [Payment utils](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/payments/utils.py): stripe helpers · Utility logic for payment session creation and verification. · `app/payments/utils.py`
- [Support](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/support/routes.py): ticketing boundary · Ticket inbox, threaded messages, and support workflows. · `app/support/routes.py`
- [Support models](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/support/models.py): support data · Tickets and message persistence for support conversations. · `app/support/models.py`

### Presentation

Shared and feature-scoped templates and browser assets.

- [Base layout](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/templates/base.html): shared templates · Global layout and shared error/auth pages. · `app/templates/base.html`
- **Feature views**: feature templates · Per-blueprint HTML templates for auth, products, orders, payments, and support.
- [Theme JS](https://github.com/aaron-pweb/pj-store-flask/blob/master/app/static/js/theme.js): browser script · Shared front-end behavior and UI theming. · `app/static/js/theme.js`

### Bootstrap

Non-request startup and provisioning entry points.

- [run.py](https://github.com/aaron-pweb/pj-store-flask/blob/master/run.py): startup · Launches the Flask app. · `run.py`
- [Admin seed](https://github.com/aaron-pweb/pj-store-flask/blob/master/create_super_admin.py): provisioning script · Creates the initial super admin account. · `create_super_admin.py`

## Connections

- run.py → App init: starts · Runtime entry initializes the Flask application.
- Admin seed → Auth models: seeds · Provisioning script depends on user/admin persistence.
- App init → Extensions: configures · App setup wires shared extensions and middleware.
- App init → Main: registers · Blueprint registration exposes the public routes.
- App init → Auth routes: registers · Blueprint registration exposes identity flows.
- App init → Products: registers · Blueprint registration exposes catalog flows.
- App init → Orders: registers · Blueprint registration exposes transaction flows.
- App init → Payments: registers · Blueprint registration exposes payment flows.
- App init → Support: registers · Blueprint registration exposes support flows.
- Auth routes → Auth models: reads/writes · Authentication and account views persist user data.
- Auth routes → Auth forms: uses · Routes bind request data to form validation.
- Auth routes → Access rules: guards · Access control decorators shape role-based entry.
- Products → Product models: reads/writes · Catalog views persist products and related records.
- Products → Product forms: uses · Product workflows rely on validated forms.
- Products → Catalog utils: uses · Routes delegate catalog-specific helper logic.
- Orders → Order models: reads/writes · Cart and order flows persist transactional state.
- Orders → Product models: consumes · Order intent is built from selected product data.
- Payments → Payment utils: uses · Payment routes delegate Stripe-specific operations.
- Payments → Order models: finalizes · Successful payment completes order state.
- Support → Support models: reads/writes · Support threads and tickets are stored separately.
- Auth routes → Base layout: renders · Identity pages share the global layout.
- Products → Feature views: renders · Catalog pages are served from feature templates.
- Orders → Feature views: renders · Order and cart views use feature-scoped templates.
- Payments → Feature views: renders · Payment UI is rendered from template pages.
- Support → Feature views: renders · Support inbox and thread views are template-driven.
- App init → Theme JS: serves · Shared static behavior is part of the app surface.
- App init → Base layout: serves · Global templates provide shared HTML structure.