======================================================================
PHARMACY MANAGEMENT SYSTEM - DEPLOYMENT README
======================================================================

This archive is ready to run on a normal PHP host or on an offline
machine. It needs no Composer step, no build step and no network access:
vendor/ already holds the autoloader and every class the application
uses. One installation is one shop with its own database. The optional
platform application is the owner console that manages several shops.

Inside the archive is a single top-level folder named "pps". Extract
it as-is. Do not rename it unless you also change the addresses below.

Read docs/installer/guide.md for the full installer manual.

----------------------------------------------------------------------
1. WHAT IS IN THE ARCHIVE
----------------------------------------------------------------------

  pps/
    .htaccess                  Apache rules (deny dotfiles, hide source)
    .env.example               template for the tenant application
    .env.production.example    template with production defaults
    composer.json              CLI script shortcuts (optional)
    README.md                  project overview and command reference
    app/                       tenant application (MVC, services)
    bin/                       maintenance and migration CLIs
    config/                    application configuration
    database/migrations/       schema files (36 migrations)
    public/                    web entry point and assets
    routes/                    web routes
    vendor/                    bundled autoloader (no download needed)
    platform/                  optional owner console
    docs/installer/guide.md    installer manual
    docs/deployment/DEPLOY-README.txt   this file
    storage/                   empty skeleton: logs, cache, tmp,
                               backups, keys, licence, uat,
                               prescriptions, migration_analysis
    platform/storage/          empty skeleton: avatars, logs

Deliberately NOT included:

  .env or any .env.bak-*     (secrets; the wizard writes the real one)
  storage/installed.lock     (a fresh copy must open the wizard)
  tests/                     (developer suites)
  docs/ apart from the two files listed above
  storage/backups, logs, tmp, uat, keys, prescriptions and uploaded
  files (customer and operational data)
  any *.sql, *.sql.gz, *.zip or *.docx file
  router.php                 (only used by the PHP built-in server)

If any of those are ever present in a copy, do not deploy that copy.

----------------------------------------------------------------------
2. REQUIREMENTS
----------------------------------------------------------------------

  PHP 8.2 or newer with these extensions enabled:
    pdo_mysql, json, mbstring, openssl, zip, fileinfo
  MySQL 5.7+/MariaDB 10.4+ with an account that can create a database,
  or an empty database created in advance.
  Apache with .htaccess support, or another server configured to send
  every request to pps/public/index.php.

The installer's first screen checks all of the above and names anything
missing.

----------------------------------------------------------------------
3. ONLINE HOST - INSTALL WITH NO SHELL ACCESS
----------------------------------------------------------------------

3.1 Create the database (either way)

  a) Let the wizard create it: give the database account CREATE rights.
  b) Or create an empty database and user in the hosting panel. In the
     wizard, untick "Create the database if it does not exist".

  The wizard refuses a database that already contains any table, so it
  can never overwrite existing data.

3.2 Upload

  With a file manager:
    1. Open the web root (htdocs, public_html or www).
    2. Upload the archive.
    3. Extract it in place. The result is <web root>/pps/...
    4. Delete the uploaded archive from the server.

  With FTP/SFTP: unzip locally, then upload the "pps" folder.

  If your host does not allow .htaccess, point the domain or a
  subfolder's document root at pps/public instead of pps/.

3.3 Permissions

  The web server user needs to create and read .env in the application
  folder and write inside storage/. On Linux hosting:

    chmod 775 pps pps/storage pps/storage/*
    chmod 664 pps/.htaccess

  Use the hosting panel's permission tool if there is no shell. After
  installation, set .env to read-only for the web server (640 or 600)
  if the host can still read it. Never make it world-readable.

3.4 Run the wizard

  Open:  https://your-domain/pps/

  That redirects to /pps/public/ and then to the setup form. Fill in:

    - pharmacy and site details (name, address, phone, time zone);
    - the application URL, for example https://your-domain/pps/public
      (use the exact address users will open; https makes the session
      cookie secure);
    - database host, port, name, username and password;
    - the first Administrator: full name, username, email and a
      password of at least 12 characters;
    - optionally install demo data (leave it off for real stock).

  The wizard creates the schema, seeds the master data, writes .env,
  writes storage/installed.lock and shows a summary. The administrator
  password is hashed and is never written to .env, the marker, the
  audit log or the page.

3.5 After installation

  - Sign in at /pps/public/login with the administrator account.
  - Open Settings and check pharmacy details, receipt text and tax.
  - Write the administrator password into the owner's password store.
  - Check storage/logs for warnings after the first sign-in.
  - Keep .env private. The bundled .htaccess denies dotfiles; confirm
    that https://your-domain/pps/.env returns 403 or 404.

  The wizard is now closed. /install shows a locked page. To rebuild the
  copy deliberately, back up the database first, then remove .env and
  storage/installed.lock and open /install again.

----------------------------------------------------------------------
4. OFFLINE SYSTEM - LAN OR STANDALONE PC
----------------------------------------------------------------------

The same archive works with no internet connection.

  1. Install XAMPP (or any Apache + PHP 8.2+ + MySQL stack).
  2. Extract the archive into the web root, for example:
       C:\xampp\htdocs\pps
  3. Start Apache and MySQL.
  4. Open http://localhost/pps/ and complete the wizard as in 3.4.
  5. For a shop network, put the machine's LAN address in the
     application URL, for example http://192.168.1.10/pps/public, and
     allow Apache through the firewall on port 80.

  No Composer, no internet and no package download is required. Keep a
  copy of the archive and a database backup on removable media for
  disaster recovery. See docs/installer/guide.md for backing up.

----------------------------------------------------------------------
5. OPTIONAL - THE PLATFORM (OWNER) CONSOLE
----------------------------------------------------------------------

Skip this section for a single shop. The platform console manages many
tenant shops. It needs a second, separate database and its own .env.

  1. Create an empty database, for example pharmacy_platform.
  2. Copy the template and edit it:

       cp platform/.env.example platform/.env

     Set PLATFORM_DB_HOST, PLATFORM_DB_PORT, PLATFORM_DB_DATABASE,
     PLATFORM_DB_USERNAME and PLATFORM_DB_PASSWORD.
     Generate a key once and keep it safe:

       php -r "echo base64_encode(random_bytes(32)), PHP_EOL;"

     Put that value in PLATFORM_KEY. Losing or changing it makes stored
     tenant database passwords unreadable.
     Set PLATFORM_OWNER_NAME, PLATFORM_OWNER_EMAIL and
     PLATFORM_OWNER_PASSWORD for the first seed only.

  3. Apply the platform schema and create the owner:

       php platform/bin/migrate.php migrate
       php platform/bin/seed.php

     Then remove PLATFORM_OWNER_PASSWORD from platform/.env. The
     password is stored only as a hash; change it from the account
     screen after the first sign-in.

  4. In the tenant application's main .env, enable tenancy:

       TENANCY_ENABLED=true
       APP_URL=https://your-domain/pps/public

     Tenant shops are then reached at /pps/public/t/<slug>/... and the
     console at /pps/platform/public/ (the platform's public folder is
     its front controller, just like the tenant app).

     On a MySQL server shared with another application, give every shop
     a slug that is not already used there. The platform derives the
     database tenant_<slug> and the MySQL account t_<slug> from the
     slug, and both are server-wide names: a clash either refuses
     provisioning ("account already exists") or lets the other
     application reset the shared account and break the shop. A
     dedicated MySQL server avoids the problem entirely.

  5. When tenant migrations are added later, roll them into every
     registered shop database:

       php platform/bin/tenant-migrate.php all

     or one shop at a time:

       php platform/bin/tenant-migrate.php <slug>

  6. Notifications the owner sends are delivered by writing directly
     into each tenant database. A failed delivery is retried from the
     platform screen ("Retry failed") or from the command line:

       php platform/bin/notify.php retry

     To retry automatically, add a scheduled task or cron entry, for
     example every 30 minutes:

       */30 * * * * cd /path/to/pps && php platform/bin/notify.php retry

     Shared hosts without cron can use the Retry button in the console.

  On hosts without shell access the platform CLIs cannot run. There is
  no browser-based platform setup in this release: run the two commands
  from a machine that has PHP 8.2+ and network access to the same MySQL
  server, or leave the platform disabled and use the tenant application
  on its own.

----------------------------------------------------------------------
6. UPGRADING AN EXISTING INSTALLATION
----------------------------------------------------------------------

  1. Back up the database and .env first (bin/backup.php or mysqldump).
  2. Replace the application files, but keep the existing .env,
     storage/ (especially keys/ and licence/) and uploaded files.
  3. Open the application. New migrations run from the shell with:

       php bin/migrate.php

     or from the platform console when the shop is a tenant.
  4. If .env is missing but the database already contains
     schema_migrations, the installer adopts the copy and writes the
     marker instead of reopening the wizard.

  Never copy another shop's .env or database into a shop. Two shops are
  two copies with separate databases, .env files and markers.

----------------------------------------------------------------------
7. TROUBLESHOOTING
----------------------------------------------------------------------

  "Access denied for user" (1045)
     Wrong database credentials, or the account cannot reach the host
     named in the form. Fix the credentials, or create an empty database
     in the panel and untick database creation.

  A tenant shop shows "the database could not be reached" (1045)
     The shop's sealed password no longer matches its MySQL account, or
     its derived t_<slug> account is shared with another application on
     the server. Check the account grants with SHOW GRANTS FOR
     't_<slug>'@'localhost' and have the server operator set a new
     password for the account and re-seal it in the platform registry.
     Give each shop a unique slug and a dedicated MySQL server where
     possible.

  "already contains N table(s)"
     The target database is not empty. Choose a new name; the wizard
     will not delete data.

  "does not exist" with creation disabled
     Create the empty database first, or tick the create option.

  Requirements page shows a red item
     Enable the named PHP extension or grant write access to the named
     folder, then use "Check again". Nothing is written while a check
     fails.

  Blank page or 500 after upload
     Confirm the PHP version, then read storage/logs. On hosts without
     .htaccess, set the document root to pps/public.

  Styles or sign-in missing
     The application URL in .env must match the address in the browser
     (scheme, host, subfolder and port).

  Top menu buttons do nothing and no dropdown opens
     Copies built before 18 November 2026 sent a Content-Security-Policy
     of script-src 'none' on every page, which blocked nav.js. Replace
     public/index.php with the file from the 18 November archive (or
     newer), then hard-reload the browser. The application pages must
     report script-src 'self'; the setup wizard keeps script-src 'none'.

  POS "Take payment" appears to do nothing
     Every refusal is written under the product search and, from the 18
     November 2026 archive, also in the bottom-right toast. Read that
     message: an empty cart, zero payment, credit without a customer, a
     closed shift, a role without the take-sale action or an expired
     session are all reported there. If no message appears at all, the
     copy is older than 18 November 2026; update and hard-reload.

  Locked installer page
     The copy is already installed. Use the sign-in link. Remove the
     marker only when rebuilding on purpose, and back up first.

======================================================================
END OF README
======================================================================
