order/README.md

# Lakeside Orders

_Demo restaurant website. The location and menu are fictional._

A dependency-light online ordering and customer-management demo for Lakeside
Orders, a fictional restaurant near the water.

## 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 and staff accounts with optional 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
- Public-domain and Creative Commons storefront photography with attribution

## 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@lakesideorders.test`
- Password: `ChangeMe123!`

Email 2FA is disabled by default for every account. It can be enabled from
**My Account** or managed by an administrator in **Users & Staff**. When 2FA is
enabled while Mailgun is disabled, 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 and open `/admin`. Accounts that opt into email 2FA complete the
six-digit email check after entering a valid password.

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 optional 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
```