# 🏗️ Media Simplified — Client-Facing Projects Hub

A **client-facing project portal** embedded inside GoHighLevel as a custom menu page. Clients log in to their GHL account and see only their own active projects — website builds, branding assets, and support tickets — with the ability to review previews, approve deliverables, request revisions, and leave feedback. All data is read from and written back to GHL in real time via the Projects Center API.

---

## 📁 Project Structure

```
client_facing_project_center/
├── projects_api.php    # Shared backend — same file as Projects Center (team view)
└── index.html          # Client-facing frontend — simplified, approval-focused UI
```

> This portal uses the **same `projects_api.php`** as the internal Projects Center but calls different actions (`get_client_projects`, `submit_client_feedback`) that filter and scope data to a single client location.

---

## 🔑 How Client Scoping Works

Every GHL location (sub-account) has a unique **Location ID**. When a client opens this page inside their GHL portal, the Location ID is automatically embedded in the URL by GHL in one of two formats:

```
/v2/location/{locationId}/custom-menu-link/projects   ← GHL sidebar nav
?locationId={locationId}                              ← iframe / widget embed
```

The frontend reads this ID on load and passes it to `projects_api.php?action=get_client_projects`. The API then scans all support tickets and returns only those belonging to that client — matched by checking three fields in priority order:

| Priority | Field | Location |
|---|---|---|
| 1 | `ticket_location_id` | On the ticket record itself |
| 2 | `main_client__location_id` | On the associated GHL Contact |
| 3 | `ticket_location_id` | On the associated GHL Contact |

This means a client never sees another client's projects, even though all tickets share the same GHL Custom Object.

---

## 📄 File Breakdown

### 1. `projects_api.php` — Backend (Shared)

See the **Projects Center README** for full API documentation. The two actions used exclusively by this client portal are:

#### `get_client_projects`
- Accepts a `locationId` POST parameter
- Scans all tickets in the Custom Object
- Filters by `detect_category()` (Website / Branding / `show_in_projects_center = Yes`)
- Matches tickets to the client's location via the 3-field lookup described above
- Returns normalized asset objects with stage labels translated for client-friendly display:

| Team Stage | Client-Facing Label |
|---|---|
| `New Request` | In Queue |
| `Pending Review` | Ready for Review |
| `Approved/ Finalize` | Approved — Going Live |
| `Complete` | Complete & Live |

- Resolved tickets are included and shown in the **Completed** tab

#### `submit_client_feedback`
- Accepts `recordId`, `contactId`, `feedback`, and `action_type` (`approve` / `revision` / `feedback`)
- Writes to GHL **Contact** custom fields:

| Action Type | Fields Written |
|---|---|
| `approve` | `asset_approval = Approve`, `asset_stage = Approved/ Finalize`, feedback if provided |
| `revision` | `asset_approval = Request updates first`, `asset_stage = New Request`, feedback text |
| `feedback` | `feedback_from_client` only — no stage change |

---

### 2. `index.html` — Client Portal Frontend

A single-file, self-contained web application styled for client consumption — clean, friendly, and focused on review and approval. No technical jargon is exposed to the client.

---

## 🧩 Features

### Left Panel — Project List

**Two-tab layout:**

| Tab | Content |
|---|---|
| **Active** | All in-progress projects and open support tickets |
| **Complete** | Finished/resolved items (tab badge turns green when items exist) |

**Within the Active tab, items are grouped:**
- `📦 Projects` — Website and branding requests
- `🎫 Support Tickets` — Items flagged as client-visible

Each list item shows:
- Category badge (🌐 Web / 🎨 Brand / 🎫 Ticket)
- Version badge (V1, V2...) if a version has been uploaded
- Animated dot — **red pulsing** if action is needed, **green** if on track
- Stage label in the client's language ("Ready for Review", "In Progress", etc.)
- **"Review Now"** badge if the item is in `Pending Review` with no approval yet
- Submitted date

**"Action Needed" badge** in the client identity row shows total number of items awaiting client review.

**Auto-open on load:** The portal automatically opens the first item that needs action. If nothing needs action, it opens the first item in the list.

---

### Right Panel — Detail View

#### Stage Timeline
A visual 4-step progress bar showing where the project currently sits:

```
📋 In Queue  →  👀 Ready for Review  →  🚀 Approved — Going Live  →  ✅ Complete & Live
```

Completed steps show a blue checkmark. The current step has a blue ring highlight. Future steps are greyed out.

#### Version Track
Pill-based version history (V1, V2, V3...) showing the current version highlighted in blue. Scales dynamically up to the current version number (minimum 3 shown).

#### Preview Frame
| Asset Type | How It Displays |
|---|---|
| `webpage` | Live iframe embed (320px tall). Falls back to "open in new tab" link if site blocks embedding. |
| `image` | Full-width image display (max 280px height, contain-fit) |
| Other types | Icon + "Open [type]" link |
| No URL yet | "Preview coming soon — our team is working on it!" placeholder |

#### Note from MS Team
A highlighted blue banner showing the team's `summary_of_asset_status_by_ms_team` field — the human-readable update for this version. Hidden if empty.

#### Conversation Thread
An inline thread showing:
- MS Team's notes (green bubble, left-aligned)
- Client's last feedback (blue bubble, right-aligned)

Displayed both in the main preview column and in the collaboration card on the right.

---

### Review & Approval Card

The approval card on the right side of the detail view is the primary client action surface.

**Approval status banner** shows one of three states:

| State | Banner Style | Message |
|---|---|---|
| No action yet | Yellow/amber | "Awaiting Your Review — Take a look and let us know!" |
| Approved | Green | "You Approved This — We're moving this to the next stage." |
| Changes requested | Red | "Changes Requested — We're working on your feedback." |

**Action buttons:**
- **✅ Approve & Advance** — Approves the asset and moves it to `Approved/ Finalize`. Disabled if already approved or not in `Pending Review`.
- **🔁 Request Changes** — Requires feedback text to be entered first. Moves asset back to `New Request`. Disabled after changes already requested.

Both buttons are disabled while an API call is in progress to prevent double-submission.

---

### Collaboration & Notes Card

A simple message thread + feedback form:
- Shows all messages (team notes + client feedback) as chat bubbles
- Textarea for typing new feedback
- **"Post Feedback"** submits without changing approval status — used for general comments
- All three action buttons (Approve, Request Changes, Post Feedback) respect a shared `cpSubmitting` lock

---

### Support Ticket View (Simplified)

When the selected item is a Support Ticket (`category === 'Support Ticket'`), the detail view switches to a simplified layout:
- Timeline and version track are **hidden** (not relevant)
- Approval and revision buttons are **hidden** (clients don't approve support tickets)
- A status card replaces the preview frame, showing ticket ID, status label, opened date, and description
- Conversation thread still shows team notes and client feedback

---

### New Request Modal

The **"＋ New Request"** button in the top-left opens a dropdown with three options:

| Option | Form URL | Opens as |
|---|---|---|
| 🌐 Website Request | `mediasimplified.io/websiterequestform` | Iframe modal |
| 🎨 Branding Request | `growsimple.tech/widget/survey/...` | Iframe modal |
| 🎫 Support Ticket | `growsimple.tech/widget/form/...` | Iframe modal |

Each form opens in a full-screen modal with a title bar and close button. Clicking outside the modal closes it.

---

## 🔄 Data Flow

```
Client opens GHL portal page
         │
         ▼
cpGetLocationId()  ← reads from URL path or query string
         │
         ▼
GET projects_api.php?action=get_client_projects&locationId={id}
         │
         ├─ Fetches all tickets from Custom Object (paginated)
         ├─ Filters by detect_category()
         ├─ Matches each ticket's contactId to the client's locationId
         │   (checks ticket field → contact field → contact fallback field)
         ├─ Fetches project_center__* fields from each matched contact
         └─ Returns normalized asset list (stage labels translated for clients)
         │
         ▼
Frontend renders:
  Left panel   — grouped list (Projects / Tickets / Completed)
  Right panel  — stage timeline, preview, approval card, conversation
  Auto-selects — first item needing action (or first item overall)

Client clicks Approve / Request Changes / Post Feedback
         │
         ▼
POST projects_api.php?action=submit_client_feedback
         │
         └─ PUT /contacts/{contactId} — writes approval + stage to GHL Contact
```

---

## ⚙️ Configuration

API endpoint in `index.html`:

```javascript
var CP_API = 'https://payments.mediasimplifiednow.com/.../projects_api.php';
```

Form URLs (in the New Request dropdown):

```javascript
// Website Request form
'https://www.mediasimplified.io/websiterequestform'

// Branding Request survey
'https://link.growsimple.tech/widget/survey/QwavIK9MGKJO1WxpiEqQ'

// Support Ticket form
'https://link.growsimple.tech/widget/form/9Cl3f19sgjofk8CAuiVv'
```

---

## 📱 Responsive Behavior

| Viewport | Layout |
|---|---|
| > 780px | Full two-panel layout (list + detail side by side) |
| 560px – 780px | Left panel narrows to 240px; action column stacks below preview |
| < 560px | Left panel hidden; detail view takes full width |

---

## 🛡️ Security & Scoping Notes

- **Client data isolation** is enforced server-side by matching `locationId` — the client cannot see other locations' projects by manipulating the URL because the server filters by the ID regardless of what is passed.
- The GHL API token is server-side only — never sent to the browser.
- No authentication layer beyond GHL's own login is added. This page should only be accessible as a GHL custom menu link or embedded widget within an authenticated GHL session.
- `cpSubmitting` flag prevents double-submission of approval/feedback actions.

---

## 🔗 Relationship to Other Systems

| System | Role |
|---|---|
| **Support Ticket Center** (`tickets_api.php` + `index.html`) | Internal team view — manages all tickets, statuses, priorities |
| **Projects Center** (`projects_api.php` + PC `index.html`) | Internal team view — manages website/branding assets, versions, milestones |
| **Client Projects Hub** (this file) | Client-facing view — scoped to one location, approval-focused |