# Deployment guide — Larspeenghar Pedigree on shared (cPanel) hosting

> **Scaling to millions of animals / thousands of users?** The flat-file
> backend described below is fine for a few thousand animals. For ~3M animals
> and ~3,000 users, use the **MySQL database backend** instead — see
> **[SCALING.md](SCALING.md)** (`schema.sql`, `db.php`, `api_db.php`,
> `migrate_import.php`). The front-end UI is the same; only the storage layer
> changes.

## What you need
- A cPanel-style shared host with **PHP 8.0+** (any cheap Hostinger / Bluehost / Namecheap plan works)
- For the scalable build: **MySQL/MariaDB** (included on Bluehost) — and for
  hundreds of concurrent users, a **VPS or dedicated** tier (see SCALING.md)
- File Manager access (or FTP)

## Files to upload to `public_html/`
Upload **all** of these to the same directory:

```
index.html       ← single entry point (landing + app combined)
styles.css
config.js
translations.js  ← landing-page translations (3 languages) — REQUIRED
sync.js          ← frontend sync layer
app.js
api.php          ← backend
.htaccess        ← protects /data/ from being downloaded
media/           ← landing assets (hero-dna.mp4 background video) — upload the folder
```

The **landing page is built into `index.html`** — it is the first thing visitors see at `yourdomain.com`. Its "Login / Enter System" buttons reveal the sign-in screen; logged-in users skip straight to the app. Visitors switch between **English / پښتو / دری** (their choice is remembered). Admins edit landing text and all three languages from **Landing & Languages** inside the app. (There is no separate `landing.html` — it was merged in.)

Do **not** upload:
- `*.bak` files
- `.prettierrc.json`
- `DEPLOY.md`
- `config.php` — **never upload this**; it is created on the server on first run and holds your deployment's data location (see "Code vs. data" below)

## After upload
1. Visit `https://yourdomain.com/`
2. Log in with default credentials:
   - **Username:** `admin`
   - **Password:** `larspeenghar2024`
3. Go to **Backup → User Management → Edit admin** and change the password immediately.

## Code vs. data — why upgrades are now safe
The app is split into three clearly separated groups:

| Group | Files | On upgrade |
|---|---|---|
| **Code** | `index.html`, `styles.css`, `config.js`, `sync.js`, `app.js`, `api.php`, `.htaccess` | ✅ Safe to overwrite — this is what you replace when upgrading |
| **Deployment config** | `config.php` | ⚠️ Created once on the server. **Never overwrite.** Holds the data-directory path. |
| **Your data** | `data/` folder | 🚫 Never overwrite or delete. This is all your animals, owners, users, settings. |

On first run the server auto-creates:
- `config.php` — one line pointing at where data lives (default: `./data`)
- `data/` folder, blocked from web access by `.htaccess`, containing:
  ```
  data/users.json        data/messages.json
  data/animals.json      data/settings.json
  data/owners.json       data/indiv_owners.json
  ```

### (Recommended) Move data above the web root for maximum safety
So a code deploy physically *cannot* touch your data, edit `config.php` on the server:
```php
return [
    'data_dir' => dirname(__DIR__) . '/pedigree_data',
];
```
This puts the data folder one level **above** `public_html`, where uploads never reach. Create the `pedigree_data` folder there once (File Manager → up one level → New Folder). Your existing data in `public_html/data/` can be moved into it.

## Upgrading without losing data
1. **Download a complete backup first**: log in as admin → **Backup → ⬇ Download Complete Backup**. This saves *everything* to one JSON file on your PC: animals & photos, herds, individual owners, messages, user logins (with credentials), certificate settings, company logo, and breed averages — captured as a verbatim snapshot of every stored key, plus the authoritative server copy when online. Restoring it returns the app to exactly that state.

> **Note:** because the backup is complete, it contains user login credentials. In local (no-PHP) mode those are plain text; once deployed on PHP they are bcrypt-hashed. Keep the backup file private.
2. Upload the new **code** files only (the 7 in the Code row above). **Do not** upload `config.php` and **do not** touch the `data/` folder.
3. Reload the site — your data is still there.
4. If anything ever goes wrong, **Backup → ⬆ Restore from File** re-imports the backup you downloaded in step 1.

## What works after Phase 1
- ✅ Login persists across browsers and cache clears (server-side session)
- ✅ Default admin always recoverable (recreated if `users.json` is missing)
- ✅ Animals saved on the server — cache clear no longer destroys data
- ✅ Per-owner scoping: non-admin users see only their own animals
- ✅ Passwords stored as bcrypt hashes (not plaintext)

## What's still browser-only (Phase 2)
The following still write to localStorage only — they will be migrated in the next session:
- Herd owners (`owners`)
- Individual owners (`indiv_owners`)
- Inbox / sent messages between users
- Pedigree certificate settings (company name, signatures, footer)
- Uploaded logo
- Breed averages

If you clear your cache before Phase 2 ships, you'll lose those specific pieces — but **animals and login will survive**.

## Troubleshooting
- **"Login failed" immediately** — likely PHP isn't enabled or `api.php` 404'd. Visit `https://yourdomain.com/api.php?action=session` directly; you should see `{"user":null}`.
- **"⚠ Sync error" indicator (bottom-left)** — the server save failed. Check browser DevTools → Network tab for the failing POST. Common cause: `data/` folder not writable. Fix: `chmod 755 data/` in File Manager.
- **Want to wipe everything and start over** — delete the `data/` folder via File Manager. The default admin will be recreated on next login.

## Security notes
- Passwords are hashed with bcrypt (PHP `password_hash`)
- Sessions use PHP's native cookie-based sessions (httpOnly)
- The `data/` directory is blocked from direct HTTP access via `.htaccess`
- For production: enable HTTPS on your domain (most cPanel hosts offer free Let's Encrypt)
