# gohighlevel/oauth-demo architecture

> Architecture diagram of the GitHub repository gohighlevel/oauth-demo, 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/oauth-demo
- Repository: https://github.com/gohighlevel/oauth-demo

## Overview

This small Express demo shows a developer-facing GHL OAuth flow: a user starts authorization, GHL returns an authorization code to the callback route, and the app exchanges it for token data. A separate refresh route exchanges a supplied refresh token. Configuration supplies client credentials and the authorization base URL. The excerpts show route registration and outbound requests; they do not show token persistence or broader API use.

Main entry points: [`lib/callback.js`](https://github.com/gohighlevel/oauth-demo/blob/main/lib/callback.js) (Code exchange), [`index.js`](https://github.com/gohighlevel/oauth-demo/blob/main/index.js) (HTTP server), [`lib/refresh.js`](https://github.com/gohighlevel/oauth-demo/blob/main/lib/refresh.js) (Refresh exchange), [`lib/initiate.js`](https://github.com/gohighlevel/oauth-demo/blob/main/lib/initiate.js) (Start authorization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Express server"]
  node_app["HTTP server<br/>[index.js]"]
  node_config["OAuth config<br/>[config.json]"]
end

subgraph group_handlers["OAuth handlers"]
  node_initiate["Start authorization<br/>[initiate.js]"]
  node_callback["Code exchange<br/>[callback.js]"]
  node_refresh["Refresh exchange<br/>[refresh.js]"]
end

subgraph group_external["GHL services"]
  node_ghl_auth["GHL authorization"]
  node_ghl_tokens["GHL token endpoint"]
end

node_user(("User"))

node_user -->|"requests routes"| node_app
node_app -->|"routes /initiate"| node_initiate
node_app -->|"routes /refresh"| node_refresh
node_app -->|"routes callback"| node_callback
node_initiate -->|"reads settings"| node_config
node_callback -->|"reads credentials"| node_config
node_refresh -->|"reads credentials"| node_config
node_initiate -->|"redirects user"| node_ghl_auth
node_ghl_auth -->|"returns code"| node_callback
node_callback -->|"exchanges code"| node_ghl_tokens
node_refresh -->|"exchanges token"| node_ghl_tokens
node_callback -->|"returns token data"| node_user
node_refresh -->|"returns token data"| node_user

click node_app "https://github.com/gohighlevel/oauth-demo/blob/main/index.js"
click node_config "https://github.com/gohighlevel/oauth-demo/blob/main/config.json"
click node_initiate "https://github.com/gohighlevel/oauth-demo/blob/main/lib/initiate.js"
click node_callback "https://github.com/gohighlevel/oauth-demo/blob/main/lib/callback.js"
click node_refresh "https://github.com/gohighlevel/oauth-demo/blob/main/lib/refresh.js"

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_app,node_config,node_user toneBlue
class node_initiate,node_callback,node_refresh toneAmber
class node_ghl_auth,node_ghl_tokens toneMint
```

## Components

### Express server

- [HTTP server](https://github.com/gohighlevel/oauth-demo/blob/main/index.js): `index.js`
- [OAuth config](https://github.com/gohighlevel/oauth-demo/blob/main/config.json): `config.json`

### OAuth handlers

- [Start authorization](https://github.com/gohighlevel/oauth-demo/blob/main/lib/initiate.js): `lib/initiate.js`
- [Code exchange](https://github.com/gohighlevel/oauth-demo/blob/main/lib/callback.js): `lib/callback.js`
- [Refresh exchange](https://github.com/gohighlevel/oauth-demo/blob/main/lib/refresh.js): `lib/refresh.js`

### GHL services

- **GHL authorization**
- **GHL token endpoint**

### Other components

- **User**

## Connections

- User → HTTP server: requests routes (evidence: `index.js`)
- HTTP server → Start authorization: routes /initiate (evidence: `index.js`)
- HTTP server → Refresh exchange: routes /refresh (evidence: `index.js`)
- HTTP server → Code exchange: routes callback (evidence: `index.js`)
- Start authorization → OAuth config: reads settings (evidence: `lib/initiate.js`)
- Code exchange → OAuth config: reads credentials (evidence: `lib/callback.js`)
- Refresh exchange → OAuth config: reads credentials (evidence: `lib/refresh.js`)
- Start authorization → GHL authorization: redirects user (evidence: `lib/initiate.js`)
- GHL authorization → Code exchange: returns code
- Code exchange → GHL token endpoint: exchanges code (evidence: `lib/callback.js`)
- Refresh exchange → GHL token endpoint: exchanges token (evidence: `lib/refresh.js`)
- Code exchange → User: returns token data (evidence: `lib/callback.js`)
- Refresh exchange → User: returns token data (evidence: `lib/refresh.js`)
