# LeathX -- Leather Chemical Trading Platform

This document covers the installation, features, daily usage, and technical architecture of LeathX, a mobile and web trading platform for the leather chemical industry.

**Estimated reading time:** 18 minutes

---

## Overview

LeathX is a bundled Progressive Web App (PWA) that provides leather chemical sourcing, recipe building, invoicing, and client management in a single offline-capable application. It runs on Android, iOS, and any modern web browser without requiring a persistent internet connection.

| Field              | Value                                      |
|--------------------|--------------------------------------------|
| App ID             | `com.interact.leatherchemos`               |
| Current version    | 11.0.0                                     |
| Android APK size   | 6.4 MB                                     |
| iOS IPA size       | 3.0 MB                                     |
| Application type   | Bundled PWA (Capacitor shell)              |
| Source file         | Single HTML/JS file (~21,000 lines)        |
| Company            | INTERACT Chemical Solutions, Karachi, Pakistan |
| Contact email      | info@interactpak.com                       |
| Contact phone      | +92 300 2020179                            |
| Web deployment     | leathx.netlify.app                         |
| Service worker     | v14 (offline-first, auto-update, background sync) |

---

## Properties

### Architecture

LeathX is a single-file PWA. The entire application -- HTML, CSS, and JavaScript -- lives in one `index.html` file wrapped in a Capacitor native shell for Android and iOS distribution. This architecture enables full offline operation because every asset is bundled into the app binary.

| Component         | Technology                                 |
|-------------------|--------------------------------------------|
| Frontend          | Vanilla HTML/CSS/JS (single file, ~21,000 lines) |
| Native wrapper    | Capacitor 8.x (Android + iOS)             |
| Data storage      | localStorage (all user data, cart, invoices) |
| Backup storage    | IndexedDB (automatic 5-minute backups)     |
| Cloud backup      | Google Drive API (optional, requires OAuth setup) |
| Live data sync    | Google Sheets (read-only, pulls pricing when online) |
| Email integration | EmailJS (free tier: 200 emails/month)      |
| Fonts             | Inter (Google Fonts, loaded when online)   |
| Service worker    | Cache-first for assets, network-first for HTML |
| Theme color       | Teal `#0D7377`                             |

### Chemical database

- 71 chemicals with pricing data, safety information (GHS/SDS classifications), and process stage assignments
- Pricing tiers update automatically from Google Sheets when the device is online
- Each chemical record includes: name, category, process stage, unit price, safety data, supplier info

### Recipe engine

- 240 leather recipe combinations derived from 5 leather types, 6 finishes, and 8 product categories
- Step-by-step formulas with exact quantities and cost calculations
- Recipes reference chemicals from the built-in database

### Solutions Hub

Five pre-configured tannery solution packages:

| Solution           | Use case                              |
|--------------------|---------------------------------------|
| Chrome Tanning     | Standard chrome tanning process       |
| Veg Retanning      | Vegetable-based retanning operations  |
| Sheepskin Nappa     | Nappa leather production from sheepskin |
| Eco-Friendly       | Environmentally compliant processing  |
| Beam House         | Pre-tanning beam house operations     |

Each solution includes a complete chemical package with quantities, process order, and total cost.

### Language support

Six languages with right-to-left (RTL) support:

| Code | Language          | Direction |
|------|-------------------|-----------|
| EN   | English           | LTR       |
| UR   | Urdu              | RTL       |
| AR   | Arabic            | RTL       |
| TR   | Turkish           | LTR       |
| CN   | Chinese           | LTR       |
| RU   | Russian           | LTR       |

The language selector is available from the sidebar menu. RTL languages automatically adjust the interface layout direction.

### Offline capability

LeathX uses a service worker with a dual-cache strategy:

- **Assets cache:** Cache-first for all static resources (HTML, icons, splash video). The app loads from cache and updates in the background.
- **Data cache:** Separate cache for Google Sheets data. The app uses cached pricing data when offline and refreshes it when connectivity returns.
- **Auto-update:** The service worker checks for new versions on every page load and polls every 30 minutes. When an update is detected, a golden "Update Now" banner appears at the top of the screen.
- **Emergency backup:** On page close, the app writes an emergency backup to localStorage.
- **Background sync:** When the device comes back online, the service worker triggers a Google Drive sync (if configured).

---

## Features

### Dashboard

The dashboard displays KPI cards and visual summaries showing sales performance, active clients, pending orders, and stock status. Data is drawn from localStorage records.

### Chemical catalog

Browse, search, and filter the 71-chemical database by:

- Process stage (beam house, tanning, retanning, finishing)
- Chemical category
- Keyword search (name, supplier)

Each chemical listing shows pricing tiers, safety classifications, and usage notes.

### Solutions Hub

Select a tannery process to view its complete chemical package. Each solution page shows:

- Required chemicals with quantities
- Process sequence
- Estimated cost per batch
- Alternative chemical substitutions

### Recipe Builder

Build leather processing recipes step by step:

1. Select the leather type (bovine, goat, sheep, buffalo, exotic).
2. Choose the finish (aniline, semi-aniline, pigmented, nubuck, suede, patent).
3. Pick the end product (shoe upper, garment, upholstery, bag, belt, glove, jacket, wallet).
4. View the generated recipe with chemicals, quantities, and costs.
5. Adjust quantities or substitute chemicals as needed.
6. Save the recipe or export it.

### Invoice creation

Create, manage, and share invoices directly from the app:

1. Open the Invoices section from the sidebar.
2. Select "New Invoice."
3. Add client details (or select an existing client from CRM).
4. Add line items from the chemical catalog or type them manually.
5. Review totals and apply any discounts.
6. Save the invoice.

**Sharing options:**

- **Email:** Requires EmailJS configuration (see the Email setup section below). Sends a formatted invoice to the client's email address.
- **WhatsApp:** Opens `wa.me` with a pre-formatted invoice summary text. The recipient can view the invoice details in the WhatsApp message.
- **Print/PDF:** Uses the browser's print dialog. Select "Save as PDF" to generate a PDF file.

### Client Intelligence / CRM

Maintain a client directory with contact details, order history, and interaction notes. Client data is stored in localStorage on the device.

### Sample requests and lab management

Track sample requests from clients and manage lab testing workflows. Log sample status, test results, and follow-up actions.

### Job orders and stock flow

Monitor job orders through their lifecycle and track chemical stock levels. Stock quantities update automatically when invoices are created.

### Field visit logging

Record field visit details including date, client visited, notes, and follow-up items. Visits are stored locally and appear in the client's CRM history.

---

## User guide

### Sign in

LeathX supports five user roles. Login credentials are listed in the `README.txt` file distributed with the app.

| Role       | Access level                              |
|------------|-------------------------------------------|
| Admin      | Full access to all features and settings  |
| Sales      | Catalog, invoices, CRM, sample requests   |
| Production | Recipes, solutions, job orders, stock flow |
| Lab        | Sample requests, lab management, recipes  |
| Field      | Field visits, CRM, catalog (read-only)    |

**To sign in:**

1. Open the app.
2. Enter your username and password on the login screen.
3. Tap "Sign In."
4. The dashboard loads with features available for your assigned role.

### Navigate the app

The sidebar menu on the left side of the screen provides access to all sections. On mobile devices, tap the hamburger icon (three horizontal lines) in the top-left corner to open the sidebar.

The bottom contact bar displays quick links for WhatsApp and email support.

### Create an invoice

1. Tap "Invoices" in the sidebar.
2. Tap the "+" or "New Invoice" button.
3. Select or enter the client name. If the client exists in CRM, their details auto-populate.
4. Tap "Add Item" to add a line item.
5. Search for a chemical by name or browse by category.
6. Enter the quantity and confirm the unit price.
7. Repeat steps 4-6 for each line item.
8. Review the invoice total at the bottom.
9. Tap "Save" to store the invoice.

**To send the invoice via WhatsApp:**

1. Open the saved invoice.
2. Tap the WhatsApp icon.
3. The app opens WhatsApp with the client's phone number and a formatted invoice summary pre-filled.
4. Tap "Send" in WhatsApp.

**To send the invoice via email:**

> **Note:** Email sending requires a one-time EmailJS setup. See the Email setup section below.

1. Open the saved invoice.
2. Tap the email icon.
3. Confirm the recipient email address.
4. Tap "Send."
5. A success or failure notification appears as a toast message.

### Use the Solutions Hub

1. Tap "Solutions Hub" in the sidebar.
2. Browse the five solution categories.
3. Tap a solution (for example, "Chrome Tanning").
4. View the chemical list, quantities, process order, and cost estimate.
5. Tap "Add to Cart" to add the entire package, or select individual chemicals.

### Build a recipe

1. Tap "Recipe Builder" in the sidebar.
2. Select the leather type from the dropdown.
3. Select the finish type.
4. Select the end product.
5. The app generates a recipe with chemicals, quantities, and cost breakdown.
6. Adjust quantities by tapping on any line item.
7. Tap "Save Recipe" to store it for future reference.

### Set up email sending

LeathX uses EmailJS (free tier: 200 emails per month) for sending invoices by email.

1. Go to [emailjs.com](https://www.emailjs.com) and create a free account.
2. Add an email service (Gmail, Outlook, or custom SMTP).
3. Create an email template with these variables: `{{to_email}}`, `{{to_name}}`, `{{subject}}`, `{{message}}`, `{{from_name}}`.
4. Copy the Service ID, Template ID, and Public Key from your EmailJS dashboard.
5. In LeathX, open the email setup screen (accessible from Settings or when first attempting to send an email).
6. Paste the Service ID, Template ID, and Public Key into the three fields.
7. Tap "Save Email Settings."
8. The app initializes EmailJS. A confirmation toast appears when the setup succeeds.

### Back up your data

LeathX performs automatic backups:

- **Every 5 minutes:** All data saves to IndexedDB (the browser's built-in database). The app keeps the last 5 timestamped backups.
- **On page close:** An emergency backup writes to localStorage.
- **Google Drive (optional):** When online and configured, data syncs to Google Drive.

**To download a manual backup:**

1. Open the browser console (or use the in-app backup button if available).
2. Call `downloadBackup()`.
3. A `.json` file downloads containing all app data.

**To restore from a backup:**

1. Call `uploadBackupFile()` from the console.
2. Select the `.json` backup file.
3. The app restores all data from the file.

---

## Technical specifications

### Build and deployment

| Platform | Build command                           | Output                                |
|----------|-----------------------------------------|---------------------------------------|
| Web      | Deploy `web/` folder to any web server  | PWA accessible via browser            |
| Android  | `./build-android.sh` (in `android/`)    | `LeatherChemOS-debug.apk`            |
| iOS      | `./build-ios.sh` (in `ios/`) + Xcode    | `.ipa` via TestFlight or direct install |
| Netlify  | Drag `web/` folder to Netlify dashboard | leathx.netlify.app                    |
| Hetzner  | `./deploy-hetzner.sh IP domain`         | Custom domain deployment              |

### Capacitor configuration

```json
{
  "appId": "com.interact.leatherchemos",
  "appName": "LeatherChem OS",
  "webDir": "web",
  "server": {
    "androidScheme": "https",
    "iosScheme": "https"
  }
}
```

### Service worker caching strategy

| Request type      | Strategy                          | Fallback                    |
|-------------------|-----------------------------------|-----------------------------|
| HTML navigation   | Network-first                     | Cache, then `./index.html`  |
| Google APIs       | Network-only                      | None                        |
| All other assets  | Cache-first (stale-while-revalidate) | Network fetch            |

### Data storage schema

All data persists in localStorage under keys prefixed with `lcos_`:

| Key prefix           | Data type                     |
|----------------------|-------------------------------|
| `lcos_chemicals`     | Chemical catalog cache        |
| `lcos_invoices`      | Invoice records               |
| `lcos_clients`       | Client/CRM records            |
| `lcos_recipes`       | Saved recipes                 |
| `lcos_samples`       | Sample request records        |
| `lcos_jobs`          | Job orders                    |
| `lcos_visits`        | Field visit logs              |
| `lcos_cart`          | Shopping cart state            |
| `lcos_emailjs_*`     | EmailJS credentials           |
| `lcos_last_modified` | Version check timestamp       |

### External connections

| Domain              | Purpose                        | Required |
|---------------------|--------------------------------|----------|
| wa.me               | WhatsApp invoice sharing       | No       |
| interactpak.com     | Company website links          | No       |
| emailjs.com / cdn.jsdelivr.net | Email sending SDK    | No       |
| fonts.googleapis.com | Inter font loading            | No       |
| docs.google.com     | Google Sheets pricing sync     | No       |
| googleapis.com      | Google Drive backup (optional) | No       |

All external connections are optional. The app functions fully offline using cached data.

### PWA manifest

| Property            | Value                                      |
|---------------------|--------------------------------------------|
| Display mode        | Standalone                                 |
| Orientation         | Any                                        |
| Background color    | `#0F1923`                                  |
| Theme color         | `#0D7377`                                  |
| Categories          | Business, Education, Productivity          |
| Icon sizes          | 72, 96, 128, 144, 152, 192, 384, 512 px   |

### File structure

```
LeatherChemOS/
  web/
    index.html         -- Main application (single-file PWA)
    portal.html        -- Buyer portal page
    download.html      -- App download page
    sw.js              -- Service worker (offline + auto-update)
    manifest.json      -- PWA manifest
    splash.mp4         -- Splash screen video
    icons/             -- App icons (72-512px + favicon)
    corporate/         -- Corporate branding assets
  android/             -- Capacitor Android build project
  ios/                 -- Capacitor iOS build project
  server/              -- Nginx config + Hetzner deploy scripts
  icons/               -- Master icon set
  DEPLOY_GUIDE.md      -- Deployment instructions
```

---

## Known limitations

| Limitation                              | Impact                                                   | Workaround                                                |
|-----------------------------------------|----------------------------------------------------------|-----------------------------------------------------------|
| Single-file architecture                | All code lives in one HTML file (~21,000 lines). Editing requires care to avoid breaking unrelated sections. | Use search to navigate. The file is organized with section comment headers. |
| No multi-user sync                      | localStorage is device-specific. Two users on different devices see different data. | Export data as JSON and share manually, or use Google Drive backup. |
| Google Sheets sync is read-only         | Pricing data pulls from Google Sheets, but changes made in the app do not write back. | Update pricing in Google Sheets directly. The app picks up changes on next sync. |
| No push notifications                   | Users are not alerted about new orders, price changes, or updates unless they open the app. | Check the app periodically. The auto-update banner appears on launch. |
| Invoice PDF uses browser print dialog   | PDF quality and formatting depend on the browser and device. No programmatic PDF generation. | Use Chrome for the most consistent print-to-PDF results. |
| localStorage capacity                   | Performance degrades after approximately 5,000 invoices. Browsers typically allow 5-10 MB of localStorage. | Archive old invoices by downloading a backup, then clear old records. |
| Offline Google Fonts                    | The Inter font requires an internet connection on first load. Subsequent loads use the browser cache. | The app falls back to system fonts (`system-ui`, `-apple-system`, `sans-serif`) when offline. |

---

## Support and contact

| Channel    | Details                                    |
|------------|--------------------------------------------|
| Email      | info@interactpak.com                       |
| Phone      | +92 300 2020179                            |
| Website    | [interactpak.com](https://interactpak.com) |
| Web app    | [leathx.netlify.app](https://leathx.netlify.app) |
| Company    | INTERACT Chemical Solutions, Karachi, Pakistan |

For bug reports, include the app version (visible in the sidebar footer), your device model, and operating system version. Attach a screenshot if the issue is visual.

---

*INTERACT Chemical Solutions -- Karachi, Pakistan*
*Version 11.0.0 -- Last updated: 2026-03-27*