# INTERACT ChemOps -- Staff Operations Portal

This document describes the features, architecture, user roles, and known limitations of the INTERACT ChemOps mobile application for staff operations management.

**Estimated reading time:** 12 minutes

---

## Overview

INTERACT ChemOps is a native mobile application that provides staff access to the INTERACT Operations Portal. The app functions as a Capacitor-wrapped shell that loads the live staff portal hosted at `app.interactpak.com/staff/login`. All business logic, data storage, and authentication run on the server -- the app itself is a lightweight native container that ensures a standalone mobile experience without opening a browser.

| Field             | Value                                          |
|-------------------|-------------------------------------------------|
| App name          | INTERACT ChemOps                                |
| App ID            | `com.interactpak.chemops`                       |
| Version           | 1.0.0                                           |
| APK size          | 4.0 MB                                          |
| IPA size          | 642 KB                                          |
| App type          | Native shell with online portal                 |
| Company           | INTERACT Solutions, Karachi, Pakistan            |
| Contact email     | info@interactpak.com                            |
| Contact phone     | +92 300 2020179                                 |
| Portal URL        | https://app.interactpak.com/staff/login         |

---

## Properties

### Architecture

ChemOps uses Capacitor 8 to wrap a minimal HTML shell inside a native Android and iOS container. On launch, the shell tests connectivity to `app.interactpak.com` and, if reachable, redirects the WebView to the live staff portal. The portal itself is a full Next.js 14 application with server-side rendering, Prisma ORM, and PostgreSQL (hosted on Neon).

- **Native container:** Capacitor 8.2 (Android + iOS)
- **Web shell:** Single HTML file (`www/index.html`, 107 lines) with inline CSS and JavaScript
- **Backend:** Next.js 14, React 18, Prisma ORM, PostgreSQL (Neon), JWT authentication (Jose library, HS256, 8-hour tokens)
- **Service worker:** Caches shell assets (`index.html`, `manifest.json`) for instant offline fallback
- **Splash screen:** 2-second display, navy background (`#12253f`)
- **Status bar:** Dark style, navy background (`#12253f`)

### Connectivity and security

The app connects to a single domain and does not load resources from any external CDN, analytics service, or third-party host.

| Allowed domain          | Purpose                        |
|-------------------------|--------------------------------|
| `app.interactpak.com`   | Staff portal (all app data)    |
| `*.interactpak.com`     | Subdomains for API calls       |

The Capacitor configuration explicitly restricts navigation to `interactpak.com` origins through the `allowNavigation` setting:

```json
"server": {
  "allowNavigation": [
    "app.interactpak.com",
    "*.interactpak.com"
  ]
}
```

Mixed content is disabled on Android (`allowMixedContent: false`). Web contents debugging is disabled in production builds.

### Standalone behavior

The app runs as a standalone native application. It does not open pages in the device browser. The PWA manifest declares `"display": "standalone"` and the Capacitor WebView handles all navigation internally.

### Offline behavior

When the device has no internet connection, the app displays a static offline screen containing:

- An "You're Offline" message panel
- A description of what requires connectivity (estimates, invoices, gate passes, CRM)
- A grid of 9 module icons (Estimates, Invoices, Gate Pass, Instructions, Followups, Recipes, CRM, Inquiries, Accounts) as visual reference
- A "Retry Connection" button

The app listens for the browser `online` event and automatically attempts reconnection when network access is restored.

> **Important:** The offline screen is informational only. No module data is cached or accessible without an active internet connection.

---

## Features

### ChemOps OS -- 6 operational modules

These six modules form the core of the ChemOps operational suite. Each module uses sequential document codes with a year-based prefix.

#### 1. Estimates

Create cost estimates with itemized line items, submit them for managerial approval, and convert approved estimates into invoices.

| Capability           | Description                                              |
|----------------------|----------------------------------------------------------|
| Create               | Build estimates with line items, quantities, and pricing |
| Sequential codes     | `EST-2026-001`, `EST-2026-002`, etc.                     |
| Approval workflow    | Submit for approval; approver accepts or rejects         |
| Share                | Send via Email (`mailto:` link) or WhatsApp (`wa.me` link) |
| Convert to invoice   | Generate a linked invoice directly from an approved estimate |

#### 2. Invoices

Generate invoices from approved estimates or create them from scratch. Record partial or full payments against each invoice.

| Capability           | Description                                              |
|----------------------|----------------------------------------------------------|
| Create               | From estimate conversion or manual entry                 |
| Sequential codes     | `INV-2026-001`, `INV-2026-002`, etc.                     |
| Approval workflow    | Submit, approve, and finalize                            |
| Payment recording    | Record payments against outstanding balances             |
| Share                | Send via Email or WhatsApp                               |

#### 3. Gate Passes

Track goods entering and leaving the facility with incoming and outgoing gate passes.

| Capability           | Description                                              |
|----------------------|----------------------------------------------------------|
| Create               | Incoming or outgoing gate passes                         |
| Sequential codes     | `GP-2026-001`, `GP-2026-002`, etc.                       |
| Approval workflow    | Approve or reject with notes                             |
| Completion tracking  | Mark gate passes as completed                            |

#### 4. Instructions

Issue directives to sales, marketing, or production teams. Assign instructions to specific staff members and track completion.

| Capability           | Description                                              |
|----------------------|----------------------------------------------------------|
| Create               | Write directives with assigned recipients                |
| Sequential codes     | `INST-2026-001`, `INST-2026-002`, etc.                   |
| Assignment           | Assign to one or more team members                       |
| Completion tracking  | Track status from open to completed                      |

#### 5. Marketing Followups

Schedule and manage customer engagement activities across the sales and marketing teams.

| Capability           | Description                                              |
|----------------------|----------------------------------------------------------|
| Schedule             | Calls, meetings, and site visits                         |
| Assignment           | Assign followups to specific team members                |
| Outcome recording    | Record results and next actions after each activity      |

#### 6. Recipes

Reference library of tannery solution formulations used in leather chemical processing.

| Capability           | Description                                              |
|----------------------|----------------------------------------------------------|
| View                 | 5 tannery solution recipes                               |
| Details              | Chemical formulations, process steps, batch cost breakdowns |

### Existing portal modules

In addition to the ChemOps OS modules, the staff portal provides access to:

| Module       | Description                                                         |
|--------------|---------------------------------------------------------------------|
| CRM          | Contact and company management with interaction history             |
| Inquiries    | Quote pipeline with status workflow tracking                        |
| Accounts     | Financial ledger                                                    |
| Dashboard    | KPI cards: Pending Approvals, Active Instructions, Upcoming Followups, Outstanding Invoices |

### Dashboard quick actions

The dashboard home screen surfaces Quick Action buttons that link directly to the most common tasks (create estimate, create invoice, create gate pass) without navigating through the sidebar.

---

## User Guide

### Launch and connect

1. Open the INTERACT ChemOps app on your device.
2. Wait for the connection indicator to finish (approximately 1.5 seconds).
   - **Online:** The app redirects to the staff portal login screen.
   - **Offline:** The app displays the offline panel with module icons and a "Retry Connection" button.

### Sign in

1. Enter your staff username in the **Username** field.
2. Enter your password in the **Password** field.
3. Tap **Sign In**.
   - The portal validates credentials against the server and issues an 8-hour JWT session token stored in an httpOnly cookie.

The portal supports 8 staff user accounts. Contact your administrator for credentials.

### Navigate modules

1. Use the **sidebar menu** (accessible from the top-left hamburger icon) to switch between modules.
2. Tap any module name to open it.
3. Use the **Quick Actions** section on the dashboard to jump directly to create screens for estimates, invoices, or gate passes.

### Create a document (estimate, invoice, or gate pass)

1. Navigate to the target module from the sidebar.
2. Tap the **Create** or **New** button.
3. Fill in the required fields (line items, quantities, pricing, recipient details).
4. Tap **Save** to save as draft, or **Submit** to send for approval.
   - The system assigns the next sequential code automatically (for example, `EST-2026-003`).

### Share a document

1. Open the document you want to share.
2. Tap **Share via Email** to open your device email client with a pre-filled message, or tap **Share via WhatsApp** to open WhatsApp with the document summary.

### Session end

On logout, the portal auto-generates a session digest email summarizing pending items and sends it to the admin account. This requires an email client configured on the device.

---

## Technical Specifications

### Build toolchain

| Component            | Version / Detail                               |
|----------------------|-------------------------------------------------|
| Capacitor Core       | 8.2.x                                           |
| Capacitor Android    | 8.2.x                                           |
| Capacitor iOS        | 8.2.x                                           |
| Capacitor Splash Screen | 8.0.x                                       |
| Capacitor Status Bar | 8.0.x                                           |
| Node.js (build)      | 25.7                                            |
| Android target SDK   | 34                                              |

### Capacitor configuration

| Setting                        | Value                     |
|--------------------------------|---------------------------|
| `appId`                        | `com.interactpak.chemops` |
| `appName`                      | `INTERACT ChemOps`        |
| `webDir`                       | `www`                     |
| `androidScheme`                | `https`                   |
| `iosScheme`                    | `https`                   |
| `webContentsDebuggingEnabled`  | `false`                   |
| `allowMixedContent`            | `false`                   |

### Service worker

The service worker (`sw.js`) uses a cache-first strategy for shell assets and a network-first strategy for portal requests. If a portal request fails (device is offline), the service worker returns the cached `index.html` shell page.

| Cache name     | Cached assets                          |
|----------------|----------------------------------------|
| `chemops-v1`   | `./`, `./index.html`, `./manifest.json` |

### Android permissions

| Permission               | Purpose                              |
|--------------------------|--------------------------------------|
| `android.permission.INTERNET` | Required for portal connectivity |

### Backend stack (server-side)

| Component        | Detail                                             |
|------------------|----------------------------------------------------|
| Framework        | Next.js 14 (App Router)                            |
| UI library       | React 18                                           |
| ORM              | Prisma                                             |
| Database         | PostgreSQL on Neon (production)                    |
| Authentication   | JWT via Jose library (HS256, 8-hour token lifetime) |
| Hosting          | Vercel (region: `fra1`)                            |
| Domain           | `app.interactpak.com`                              |

---

## Roles and Permissions

The portal enforces role-based access control (RBAC). Each user is assigned one role that determines which modules and actions they can access.

| Role               | Example user | Estimates | Invoices | Gate Passes | Instructions | Followups | Recipes | CRM | Inquiries | Accounts | Audit Trail |
|--------------------|-------------|-----------|----------|-------------|-------------|-----------|---------|-----|-----------|----------|-------------|
| Admin              | --          | Full      | Full     | Full        | Full        | Full      | Full    | Full | Full     | Full     | View        |
| Chemical Engineer  | Khalid      | Create, Approve | Create, Approve | Create, Approve | Create, Approve | Create, Approve | Edit | View | View | View | -- |
| Manager            | --          | View, Approve | View, Approve | View, Approve | View, Approve | View, Approve | View | Full | Full | View | -- |
| Accounts           | --          | Edit, Approve | Edit, Approve | View | View | View | View | View | View | Full | -- |
| Merchandiser       | --          | Edit      | View     | View        | View        | Edit      | View    | View | View     | View     | -- |
| Fabricator         | --          | View      | View     | Edit        | View        | View      | View    | View | View     | View     | -- |
| Office Staff       | --          | View      | View     | View        | View        | Edit      | View    | View | View     | View     | -- |

**Permission levels:**
- **Full** -- Create, read, update, delete, and approve
- **Edit** -- Create, read, and update
- **View** -- Read-only access
- **Approve** -- Submit approval decisions (accept or reject)

---

## Known Limitations

| Category             | Limitation                                                       |
|----------------------|------------------------------------------------------------------|
| Connectivity         | Requires an active internet connection for all operations. No data is cached for offline use beyond the static shell screen. |
| Offline mode         | Displays a static grid of 9 module icons and a retry button. No module functionality is available offline. |
| Push notifications   | Not supported. Users must open the app to check for updates.     |
| Email sharing        | Uses `mailto:` links. Requires an email client installed and configured on the device. |
| WhatsApp sharing     | Opens `wa.me` links. Requires WhatsApp installed on the device.  |
| Audit trail          | Visible to the admin role only.                                  |
| Session digest       | Generated on logout. Requires an email client on the device to send. |
| iOS signing          | The iOS build (IPA) is unsigned. Requires an Apple Developer account and Xcode for distribution. |
| Real-time updates    | No real-time collaboration or live data push. Changes made by other users become visible after a manual page refresh. |
| Session duration     | JWT tokens expire after 8 hours. Users must sign in again after expiration. |
| Orientation          | Portrait-only (`"orientation": "portrait"` in manifest).         |

---

## Support and Contact

| Channel   | Detail                                           |
|-----------|--------------------------------------------------|
| Email     | info@interactpak.com                             |
| Phone     | +92 300 2020179                                  |
| Website   | https://interactpak.com                          |
| Portal    | https://app.interactpak.com                      |
| Company   | INTERACT Solutions, Karachi, Pakistan            |

For technical issues with the mobile app shell (crashes on launch, splash screen hangs, WebView rendering errors), contact the development team with the device model, OS version, and a screenshot of the error.

For portal access issues (forgotten password, role changes, module permissions), contact your system administrator.

---

*INTERACT ChemOps v1.0.0 -- INTERACT Solutions, Karachi, Pakistan*