order/README.md

# Fat Bottom Grille e-Commerce

A dependency-light online food ordering system for Fat Bottom Grille at
410 W Piedmont St in Keyser, West Virginia.

## Included

- Configurable menu categories, items, prices, availability, images, and tags
- Homepage specials that automatically adapt to the number currently active
- Persistent cart and abandoned-cart tracking
- Configurable state, city, and county tax rates
- Pickup checkout with Square Web Payments and Payments API support
- Customer accounts with email verification, email 2FA, captcha, and honeypots
- Customer order history, saved pickup details, password changes, and newsletter preferences
- Staff order queue, status history, internal notes, and Square refunds
- Staff roster and role management
- Visitor, order, sales, popular-item, subscriber, and abandoned-cart statistics
- Styled menu PDF and order CSV exports
- Mailgun transactional email and newsletter delivery
- Automatic newsletter unsubscribe links
- SQLite by default with an optional MySQL/MariaDB copy-and-switch tool
- JSON-backed business, ordering, Square, Mailgun, and database settings

## Requirements

- PHP 8.1 or newer
- PHP extensions: PDO, PDO SQLite, cURL, JSON, and sessions
- Optional: `pdo_mysql` for MySQL/MariaDB migration

No Composer, Node.js, MySQL server, Square account, or Mailgun account is
required for local development.

## Start Locally

```bash
php -S 127.0.0.1:8080 -t public public/router.php
```

Open [http://127.0.0.1:8080](http://127.0.0.1:8080).

The application creates its SQLite database, JSON settings, sessions, and mail
log inside `storage/` on first request.

Before public use, enter the restaurant's verified phone number, email address,
and hours in **Dashboard > Settings**. They are intentionally not invented in
the default configuration.

## Apache Routing

The repository includes two rewrite configurations:

- `public/.htaccess` when the Apache `DocumentRoot` points to `public/`
- `.htaccess` when shared hosting exposes the repository directory itself

Apache must have `mod_rewrite` enabled and must permit `.htaccess` overrides.
A typical virtual host uses:

```apache
DocumentRoot /path/to/fatbottomgrille/public

<Directory /path/to/fatbottomgrille>
    AllowOverride All
    Require all granted
</Directory>
```

The preferred setup is to point the web root at `public/`. If the application
is installed in a URL subdirectory, generated links, form actions, redirects,
and assets automatically include that subdirectory.

## Initial Administrator

- Email: `admin@fatbottomgrille.com`
- Password: `ChangeMe123!`

Mailgun is disabled by default, so the six-digit sign-in code appears in the
browser and is also written to `storage/logs/mail.log`.

Change the initial password from **My Account** before deploying the site.

## Dashboard

Sign in, complete email verification, and open `/admin`.

The dashboard controls:

- Menu categories and food items
- Homepage specials and schedules
- Orders, fulfillment status, notes, and refunds
- Customers and staff roles
- Business information and ordering availability
- Tax rates
- Square and Mailgun credentials
- Newsletters
- Menu PDF and order CSV exports
- MySQL/MariaDB connection and migration

## Square

Checkout runs in clearly labeled demo mode until Square is enabled.

In **Dashboard > Settings**, enter matching Square environment credentials:

1. Application ID
2. Location ID
3. Access token
4. Environment (`sandbox` or `production`)
5. Enable Square payments

The browser tokenizes card details with Square Web Payments. Card data is never
posted to or stored by this application. The server sends the token and
server-calculated amount to `POST /v2/payments`.

## Mailgun

In **Dashboard > Settings**, enter the Mailgun domain, API key, sender name,
and sender email, then enable Mailgun.

When Mailgun is disabled, messages are stored locally in
`storage/logs/mail.log`. This keeps registration, 2FA, order confirmation, and
newsletter workflows testable without an email service.

## SQLite and MySQL/MariaDB

SQLite is the default runtime database:

```text
storage/database/store.sqlite
```

To migrate, save the MySQL/MariaDB connection in **Dashboard > Settings**, then
run the migration tool. It creates the target database, copies every
application table and row, and can optionally switch the application driver.

Keep SQLite selected unless the MySQL/MariaDB server is reliably available.

## Production Checklist

1. Set the public application URL and verified business contact details in the dashboard.
2. Change the initial administrator password.
3. Enable HTTPS and secure cookies at the web server.
4. Configure Mailgun and verify its sending domain.
5. Test Square in sandbox before enabling production credentials.
6. Confirm tax rates with the business's tax professional.
7. Back up `storage/database/store.sqlite` and `storage/config/settings.json`.
8. Point the web server document root to `public/`.

## Project Layout

```text
app/Core/          HTTP, configuration, database, auth, security, and views
app/Controllers/   Storefront, account, and dashboard request handlers
app/Services/      Cart, orders, payment, email, stats, PDF, and migration
config/            Safe application defaults
public/            Web document root and frontend assets
views/             Storefront, account, and dashboard templates
storage/           Runtime database, JSON settings, sessions, and logs
```