How aaron-pweb/pj-store-flask works
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: __init__.py App init · auth/routes.py Auth routes · products/routes.py Products · orders/routes.py Orders
Components 22
Flask app
Application package and shared startup wiring.
- App init · Creates and configures the Flask application package.
app/__init__.py - Extensions · Central Flask extension wiring such as database, auth, and CSRF.
app/extensions.py
Feature blueprints
Business domains implemented as Flask blueprints.
- Main · Public landing and unauthenticated entry routes.
app/main/routes.py - Auth routes · Login, signup, profile, dashboards, and admin/user management flows.
app/auth/routes.py - Auth models · Users, roles, addresses, and related security data.
app/auth/models.py - Auth forms · Forms for login, signup, profile, and address workflows.
app/auth/forms.py - Access rules · Role constants and decorators for protected views.
app/auth/decorators.py - Products · Catalog browsing, product management, variants, reviews, and wishlist flows.
app/products/routes.py - Product models · Product, category, variant, and review persistence.
app/products/models.py - Product forms · Forms for product, category, review, and related editing flows.
app/products/forms.py - Catalog utils · Supporting logic for product-related operations.
app/products/utils.py - Orders · Cart, checkout address selection, order detail/history, and returns.
app/orders/routes.py - Order models · Cart and order persistence used across purchase and fulfillment flows.
app/orders/models.py - Payments · Checkout/payment session routes and success handling.
app/payments/routes.py - Payment utils · Utility logic for payment session creation and verification.
app/payments/utils.py - Support · Ticket inbox, threaded messages, and support workflows.
app/support/routes.py - Support models · Tickets and message persistence for support conversations.
app/support/models.py
Presentation
Shared and feature-scoped templates and browser assets.
- Base layout · Global layout and shared error/auth pages.
app/templates/base.html - Feature views · Per-blueprint HTML templates for auth, products, orders, payments, and support.
- Theme JS · Shared front-end behavior and UI theming.
app/static/js/theme.js
Bootstrap
Non-request startup and provisioning entry points.
- run.py · Launches the Flask app.
run.py - Admin seed · Creates the initial super admin account.
create_super_admin.py
Connections 27
- 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.