Muffin Shop

A webapp for small ecommerce sites. Features include: shopping cart, inventory tracking, Stripe integration, basic admin, login system, and emails.

This is a work in progress. The functionality is somewhat modular; see MODULES.md for more information about how modules work.

Live Instances

• Rainey Arcade (shop module used for virtual products)
• Jade Thompson's art portfolio (gallery module + blog)

Current Goal

• Make an instance for The Rainbow Farm (shop module used for real products)

Long-Term Goal

• Allow different websites with similar functionality to share a codebase
• Example: Website A is an online shop with a blue theme and a gallery to showcase images.
• Example: Website B is an online shop with a red theme and a simple blog.
• Example: Website C is a simple blog with a white theme and a gallery to showcase images.

Dependencies

1. Linux
2. Python 3.10+
3. uWSGI
4. Flask
5. Huey (a task queuer for sending email)
6. SQL-Alchemy
7. WTForms
8. Stripe
9. Webpack
10. ReactJS (for the shop & gallery modules)
11. See setup.py and package.json for more detail

Setup on Ubuntu Server 22.04

1. Install npm
2. npm install in this directory.
3. npm run build to bundle/compile static resources with Webpack.
4. Create a Python virtual env, activate it. sudo apt install python3-venv; python3 -m venv env; source env/bin/activate
5. Do pip install . in the root of this repo.
6. Use python3 scripts/database.py new to create a new database.
7. Use the scripts/dev-backend.sh shell script to run a development uWSGI server (localhost:5000).
8. OR use python3 -m muffin_shop for Flask's built-in development server (this will also put Flask in debug mode).
9. See the readme inside /install for help with setting up a production server.

Customizing a New Instance

1. A .env file will auto-generate after the first run. It holds secrets, so keep it safe.
2. You can also generate the .env file by running python3 scripts/manage.py init
3. Set CONFIG_PATH to the instance's config directory (copy config/client/skel for a template)
4. Note: The skeleton config is a mixture of symlinks and copies to maximize my convenience.
5. Example config path: config/client/<instance_name>
6. Create static/client/<instance_name> and make css, img, js dirs as needed for static assets
7. The config/client/<instance_name>/modules.json file defines what modules are loaded and which is the main index.

Upgrading

1. Stop running server with systemctl.
2. Go to the root of this repo.
3. git pull the new code.
4. Run prod-build.sh to bundle/compile/hocuspocus the JavaScript.
5. Activate the venv and pip install .
6. flask db upgrade to apply any database migrations.
7. To use the flask command you must have FLASK_APP in your environment (the .env file).

Development

1. Run scripts/dev-frontend.sh to open a split-pane tmux session with live-reloading backend and frontend.
2. Run scripts/dev-backend.sh for just a live-reloading backend.
3. Run python scripts/database.py test --shop for an example database with products in the shop.
4. Run scripts/dev-shop.sh to replace any existing db with a shop-testing db, and run scripts/dev-frontend.sh

How it works

1. Systemd starts Nginx and uWSGI
2. Nginx serves files from /static directly and passes the other requests through to uWSGI
3. uWSGI creates worker processes each running a Python interpreter. Each worker imports the application callable (Flask object) from muffin_shop/run.py.
4. The WSGI application is created by the Main module, specifically by create_app defined in muffin_shop/helpers/main/app_factory.py
5. When uWSGI receives a connection, it picks one of its idle workers and calls the WSGI application in that process.

Style

• Black formatter for Python
• Prettier formatter for everything else
• Except HTML because Jinja templates aren't easy to format
• Unix line endings
• Absolute Python imports only

Terminology

• route: A URL fragment such as "/" or "/about". Used to create a URL map
• controller: Function that responds to a user request, returning eiher a template (HTML) or JSON
  • in Flask terms: a function registered with the decorator @blueprint.route which becomes a value in the app.view_functions dictionary
  • in Django terms: a view function (same idea, different boilerplate)
• template: HTML file using Jinja templating engine to embed data injected by the controller
• model: A class-based abstraction on top of database tables, using SQLAlchemy
• form: A class-based abstraction on top of HTML forms which provides validators for the user input, using WTForms
• helper: Pure function that can be shared throughout the codebase

Directory Structure

/static

• Files that can be cached / files served traditionally by the web server (e.g., images, CSS, JavaScript)

/config

• Site-specific configuration including logging, modules, html templates, markdown
• This is only for configuration that can be committed to source control
• Note: Site-specific secrets should be in .env files (e.g., .env.my_site.production)

/config/skel

• "Skeleton" for a new site-specific config - basically a ton of symlinks you can selectively replace

/src

• Core pieces of the module system needed by every module
• Entrypoint: run.py

/src/controllers/<module>

• Functions registered to routes (URL endpoints) which could return a template or JSON

/src/models/<module>

• Models shape data in the database (using SQLAlchemy)
• Models manipulate data at the request of controllers

/src/forms/<module>

• Server-side form validation using WTForms

/src/helpers/<module>

• Extra helpers for modules such as utility functions, Flask plugins, asynchronous tasks

/src/react

• React components to be bundled by Webpack (outputs into /static/js/dist)