# Pharmacy System Starter

## What This Is

A starter/boilerplate for building online pharmacy e-commerce sites. It's a hybrid **Laravel 11 + legacy PHP** application — Laravel handles routing, migrations, Eloquent, and service providers, but much of the business logic lives in a legacy class-based structure under `core/`, `shop/`, and `cms/`.

This repo serves as the **upstream source** for all customer projects. Customer projects are initialised from this repo using `init-customer-project.sh` and maintain a connection back via a dedicated `upstream` branch. See `git_workflow_customer_projects.md` for the full workflow.

## Architecture

### Directory Structure

```
app/                    # Laravel application (controllers, providers)
core/                   # Legacy core framework (classes, includes, CSS, JS)
  ├── classes/          # Core PHP classes (classmap autoloaded)
  ├── includes/         # Bootstrap (header.inc.php is the main entry point)
  ├── src/              # PSR-4 namespace: Mtc\Core\
  ├── css/              # Core stylesheets and mixins
  └── js/               # Core JS (TinyMCE, admin scripts)
shop/                   # E-commerce layer
  ├── classes/          # Shop PHP classes (classmap autoloaded)
  ├── src/              # PSR-4 namespace: Mtc\Shop\
  └── checkout/         # Checkout flow
cms/                    # Content management system
  ├── classes/          # CMS PHP classes (classmap autoloaded)
  └── src/              # PSR-4 namespace: Mtc\Cms\
modules/                # Feature modules (PSR-4: Mtc\Modules\)
  ├── Members/          # Authentication, registration, member area
  ├── BasketRecovery/   # Abandoned basket recovery
  ├── FormBuilder/      # Dynamic form builder
  └── ...
plugins/                # Plugins (PSR-4: Mtc\Plugins\ and MtcPharmacy\)
  ├── RyftPay/          # Payment processing
  ├── BasketBuilder/    # Basket construction
  ├── Wisebee/          # Wisebee video consultation integration
  └── ...
sites/                  # Site themes (customer-specific overrides)
  ├── loader.php        # Theme resolver (by domain, cookie, or fallback)
  ├── sites.php         # Domain-to-theme mapping
  └── default/          # Default theme (templates, CSS, JS, settings)
routes/                 # Laravel routes (web.php, api.php)
config/                 # Laravel config (most values pulled from .env)
database/migrations/    # Timestamp-prefixed Laravel migrations
```

### Theme/Site System

The site system in `sites/loader.php` resolves themes by domain → cookie → fallback. It defines `THEME_PATH` and `DEFAULT_THEME_PATH`, enabling a **template override pattern**: customer projects place customised files in `sites/clientname/` and everything else falls through to `sites/default/`.

### Autoloading

Defined in `composer.json`:
- **PSR-4**: `App\`, `Mtc\Core\`, `Mtc\Shop\`, `Mtc\Cms\`, `Mtc\Modules\`, `Mtc\Plugins\`, `MtcPharmacy\*`
- **Classmap**: `core/classes`, `shop/classes`, `cms/classes`
- **Files**: `core/includes/functions.php`, `shop/includes/functions.php`, `cms/includes/functions.php`

## Tech Stack

- **PHP**: ^8.4
- **Framework**: Laravel 11 (hybrid with legacy code)
- **Templates**: Twig 3 (not Blade)
- **Frontend**: Vite (migrated from Webpack), Vue 2, LESS for styles
- **JS entry**: `sites/default/js/app.js`
- **CSS globals**: `sites/default/css/variables.less`, `core/css/mixins.less`
- **Testing**: PHPUnit 10
- **Database**: MySQL/MariaDB

### Vite Aliases

```
@site       → sites/default
@core       → core
@components → sites/default/js/components
@plugins    → plugins
@shop       → shop
```

## Commands

```bash
# Run tests
vendor/bin/phpunit

# Build frontend
npm run build

# Dev server (requires APP_DOMAIN and SSL certs on staging)
npm run dev

# Laravel
php artisan migrate
php artisan cache:clear
php artisan twig:clear

# Initial setup (new install)
sh setup.sh

# Deployment (called by Envoyer)
sh deploy.sh
```

## Git Workflow

### Starter Repo (this repo)

- Default branch: `master`
- Branch prefixes: `feature/`, `bugfix/`, `hotfix/`, `improvement/`, `release/`
- All work merged via PR into `master`
- Tag releases with semver (e.g. `v1.1.0`) and update `CHANGELOG.md`

### Customer Projects

Customer projects use a three-branch model:
- `main` — production (deployed via Envoyer)
- `develop` — staging/development
- `upstream` — clean tracking branch, only receives commits from this starter

Two remotes: `origin` (customer repo), `starter` (this repo).

See `git_workflow_customer_projects.md` for full details and `init-customer-project.sh` to create a new customer project.

## Deployment

- **Tool**: Laravel Envoyer with Bitbucket webhooks
- **Script**: `deploy.sh` — clears caches, runs composer install (no-dev), migrates, builds frontend, publishes assets, installs crons
- **Health check**: `GET /health` — verifies DB connectivity, used by Envoyer for automatic rollback
- **CI**: Bitbucket Pipelines (`bitbucket-pipelines.yml`) — runs PHPUnit on every PR

## Key Conventions

- Config values should come from `.env` via `env()` — see `config/site.php` for the pattern
- Customer-specific code belongs in `sites/clientname/`, not in core/shop/cms
- Customer migrations should be prefixed with `client_` to distinguish from starter migrations
- The `sites/default/settings/settings.db.php` file is auto-generated from the admin area — treat the customer's version as authoritative during upstream merges
- Private Composer repos: `composer.mtcassets.com`, `satis.wisebee.app`

## Documentation

- [Internal Git Workflow](./git_workflow_internal.md)
- [Customer Project Workflow & Deployment](./git_workflow_customer_projects.md)
- [Vite Migration Notes](./VITE-MIGRATION.md)
- [Component Registry](./COMPONENT_REGISTRY.md)
- [Changelog](./CHANGELOG.md)
