# gohighlevel/ghl-marketplace-app-template architecture

> Architecture diagram of the GitHub repository gohighlevel/ghl-marketplace-app-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gohighlevel/ghl-marketplace-app-template
- Repository: https://github.com/gohighlevel/ghl-marketplace-app-template

## Overview

This repository is a GoHighLevel Marketplace app template: an Express server handles OAuth installation, example company/location API requests, webhooks, SSO decryption, and serves a Vue custom-page UI. The principal flow exchanges an authorization code for installation tokens, keeps tokens in an in-memory model, then uses them for authenticated API calls. The UI can request encrypted SSO data from its parent frame and submit it to the server for decryption. Connections reflect README statements or shown calls; the UI/server wiring is documented, while persistent storage is not present.

Main entry points: [`src/index.ts`](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/index.ts) (HTTP routes), [`src/ghl.ts`](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ghl.ts) (API client), [`src/ui/src/ghl/index.js`](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ui/src/ghl/index.js) (SSO browser helper), [`src/ui/src/App.vue`](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ui/src/App.vue) (Vue app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Express Server"]
  node_server_routes["HTTP routes<br/>[index.ts]"]
  node_ui_serving["Static UI serving<br/>[index.ts]"]
end

subgraph group_integration["GHL Integration"]
  node_oauth_flow["OAuth handling<br/>[ghl.ts]"]
  node_ghl_client["API client<br/>[ghl.ts]"]
  node_location_token["Location token exchange<br/>[ghl.ts]"]
  node_sso_decrypt["SSO decryption<br/>[ghl.ts]"]
end

subgraph group_ui["Custom Page UI"]
  node_vue_app["Vue app<br/>[App.vue]"]
  node_vue_bootstrap["UI bootstrap<br/>[main.js]"]
  node_ui_ghl["SSO browser helper<br/>[index.js]"]
  node_welcome_view["Welcome view<br/>[HelloWorld.vue]"]
end

subgraph group_state["Installation State"]
  node_installation_state["Installation tokens<br/>[model.ts]"]
end

node_marketplace(("GHL Marketplace"))
node_browser(("Browser / iframe"))
node_ghl_api["GoHighLevel API"]
node_oauth_provider["GHL OAuth service"]
node_parent_app(("GHL parent app"))
node_webhook_sender(("Webhook sender"))

node_marketplace -->|"starts authorization"| node_server_routes
node_server_routes -->|"handles code"| node_oauth_flow
node_oauth_flow -->|"exchanges code"| node_oauth_provider
node_oauth_flow -->|"saves installation"| node_installation_state
node_server_routes -->|"requests company data"| node_ghl_client
node_server_routes -->|"requests location data"| node_ghl_client
node_ghl_client -->|"reads and updates tokens"| node_installation_state
node_ghl_client -->|"sends authenticated requests"| node_ghl_api
node_server_routes -->|"requests location token"| node_location_token
node_location_token -->|"exchanges company token"| node_ghl_api
node_location_token -->|"saves location install"| node_installation_state
node_ghl_client -->|"refreshes token"| node_oauth_provider
node_oauth_provider -->|"returns refreshed tokens"| node_installation_state
node_webhook_sender -->|"posts events"| node_server_routes
node_server_routes -->|"decrypts submitted key"| node_sso_decrypt
node_parent_app -->|"sends SSO data"| node_ui_ghl
node_ui_ghl -->|"requests SSO data"| node_parent_app
node_ui_ghl -->|"posts key for decryption"| node_server_routes
node_sso_decrypt -->|"returns decrypted data"| node_server_routes
node_vue_bootstrap -->|"mounts"| node_vue_app
node_vue_bootstrap -->|"registers helper"| node_ui_ghl
node_vue_app -->|"requests user data"| node_ui_ghl
node_vue_app -->|"renders"| node_welcome_view
node_browser -->|"loads custom page"| node_ui_serving
node_ui_serving -->|"serves UI assets"| node_vue_app

click node_server_routes "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/index.ts"
click node_ui_serving "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/index.ts"
click node_oauth_flow "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ghl.ts"
click node_ghl_client "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ghl.ts"
click node_location_token "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ghl.ts"
click node_sso_decrypt "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ghl.ts"
click node_installation_state "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/model.ts"
click node_vue_app "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ui/src/App.vue"
click node_vue_bootstrap "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ui/src/main.js"
click node_ui_ghl "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ui/src/ghl/index.js"
click node_welcome_view "https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ui/src/components/HelloWorld.vue"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_routes,node_ui_serving,node_browser toneBlue
class node_oauth_flow,node_ghl_client,node_location_token,node_sso_decrypt toneAmber
class node_vue_app,node_vue_bootstrap,node_ui_ghl,node_welcome_view,node_ghl_api,node_webhook_sender toneMint
class node_installation_state toneRose
class node_marketplace,node_oauth_provider,node_parent_app toneIndigo
```

## Components

### Express Server

- [HTTP routes](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/index.ts): `src/index.ts`
- [Static UI serving](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/index.ts): `src/index.ts`

### GHL Integration

- [OAuth handling](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ghl.ts): `src/ghl.ts`
- [API client](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ghl.ts): `src/ghl.ts`
- [Location token exchange](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ghl.ts): `src/ghl.ts`
- [SSO decryption](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ghl.ts): `src/ghl.ts`

### Custom Page UI

- [Vue app](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ui/src/App.vue): `src/ui/src/App.vue`
- [UI bootstrap](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ui/src/main.js): `src/ui/src/main.js`
- [SSO browser helper](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ui/src/ghl/index.js): `src/ui/src/ghl/index.js`
- [Welcome view](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/ui/src/components/HelloWorld.vue): `src/ui/src/components/HelloWorld.vue`

### Installation State

- [Installation tokens](https://github.com/gohighlevel/ghl-marketplace-app-template/blob/main/src/model.ts): `src/model.ts`

### Other components

- **GHL Marketplace**
- **Browser / iframe**
- **GoHighLevel API**
- **GHL OAuth service**
- **GHL parent app**
- **Webhook sender**

## Connections

- GHL Marketplace → HTTP routes: starts authorization (evidence: `README.md`)
- HTTP routes → OAuth handling: handles code (evidence: `src/index.ts`)
- OAuth handling → GHL OAuth service: exchanges code (evidence: `src/ghl.ts`)
- OAuth handling → Installation tokens: saves installation (evidence: `src/ghl.ts`)
- HTTP routes → API client: requests company data (evidence: `src/index.ts`)
- HTTP routes → API client: requests location data (evidence: `src/index.ts`)
- API client → Installation tokens: reads and updates tokens (evidence: `src/ghl.ts`)
- API client → GoHighLevel API: sends authenticated requests (evidence: `src/ghl.ts`)
- HTTP routes → Location token exchange: requests location token (evidence: `src/index.ts`)
- Location token exchange → GoHighLevel API: exchanges company token (evidence: `src/ghl.ts`)
- Location token exchange → Installation tokens: saves location install (evidence: `src/ghl.ts`)
- API client → GHL OAuth service: refreshes token (evidence: `src/ghl.ts`)
- GHL OAuth service → Installation tokens: returns refreshed tokens
- Webhook sender → HTTP routes: posts events (evidence: `README.md`)
- HTTP routes → SSO decryption: decrypts submitted key (evidence: `src/index.ts`)
- GHL parent app → SSO browser helper: sends SSO data (evidence: `src/ui/src/ghl/index.js`)
- SSO browser helper → GHL parent app: requests SSO data (evidence: `src/ui/src/ghl/index.js`)
- SSO browser helper → HTTP routes: posts key for decryption (evidence: `src/ui/src/ghl/index.js`)
- SSO decryption → HTTP routes: returns decrypted data (evidence: `src/index.ts`)
- UI bootstrap → Vue app: mounts (evidence: `src/ui/src/main.js`)
- UI bootstrap → SSO browser helper: registers helper (evidence: `src/ui/src/main.js`)
- Vue app → SSO browser helper: requests user data (evidence: `src/ui/src/App.vue`)
- Vue app → Welcome view: renders (evidence: `src/ui/src/App.vue`)
- Browser / iframe → Static UI serving: loads custom page (evidence: `README.md`)
- Static UI serving → Vue app: serves UI assets (evidence: `README.md`)
