# limesharp/shopify-onboarding architecture

> Architecture diagram of the GitHub repository limesharp/shopify-onboarding, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/limesharp/shopify-onboarding
- Repository: https://github.com/limesharp/shopify-onboarding

## Overview

This is a read-only, multi-store Shopify audit-data collector. Its main workflow loads each store’s credentials, refreshes tokens when needed, verifies access, collects configuration and privacy data through the Admin GraphQL API, then writes JSON and ClickUp-ready Markdown. A separate authorization workflow obtains and persists offline tokens through a relay. The README documents manual app/integration review as a product capability, but no automated inventory is implemented. Query-module call paths are shown where excerpts support them; relay internals were not sampled.

Main entry points: [`src/index.ts`](https://github.com/limesharp/shopify-onboarding/blob/main/src/index.ts) (Multi-store runner), [`src/client.ts`](https://github.com/limesharp/shopify-onboarding/blob/main/src/client.ts) (Admin API client), [`src/auth.ts`](https://github.com/limesharp/shopify-onboarding/blob/main/src/auth.ts) (OAuth CLI), [`src/queries/store-setup.ts`](https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/store-setup.ts) (Store setup queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and credentials"]
  node_oauth_cli["OAuth CLI<br/>[auth.ts]"]
  node_relay["OAuth relay<br/>[relay.ts]"]
  node_token_exchange["Token exchange<br/>[auth.ts]"]
  node_env_writer["Environment writer<br/>[env-writer.ts]"]
  node_store_config["Store configuration<br/>[config.ts]"]
  node_token_refresh["Token refresh<br/>[token-refresh.ts]"]
end

subgraph group_collection["Audit collection"]
  node_collector["Multi-store runner<br/>[index.ts]"]
  node_api_client["Admin API client<br/>[client.ts]"]
  node_auth_check["Connectivity check<br/>[auth-check.ts]"]
  node_store_setup["Store setup queries<br/>[store-setup.ts]"]
  node_query_helpers["Query helpers<br/>[helpers.ts]"]
  node_apps_integrations["Apps and integrations"]
  node_tracking_compliance["Tracking and compliance"]
end

subgraph group_outputs["Audit outputs"]
  node_output_writer["JSON writer<br/>[output.ts]"]
  node_clickup_docs["ClickUp documents<br/>[clickup-doc.ts]"]
  node_audit_files["Audit files"]
end

subgraph group_integrations["External systems"]
  node_shopify[("Shopify stores")]
  node_manual_review["Manual app review"]
end

node_operator(("Operator"))

node_operator -->|"starts authorization"| node_oauth_cli
node_oauth_cli -->|"polls for code"| node_relay
node_shopify -.->|"approves installation"| node_relay
node_oauth_cli -->|"exchanges code"| node_token_exchange
node_token_exchange -->|"requests token"| node_shopify
node_oauth_cli -->|"saves credentials"| node_env_writer
node_token_refresh -->|"persists refreshed tokens"| node_env_writer
node_operator -->|"runs collection"| node_collector
node_collector -->|"loads stores"| node_store_config
node_collector -->|"refreshes tokens"| node_token_refresh
node_collector -->|"builds client"| node_api_client
node_collector -->|"verifies access"| node_auth_check
node_collector -->|"collects setup"| node_store_setup
node_collector -->|"runs section"| node_apps_integrations
node_collector -->|"collects compliance"| node_tracking_compliance
node_auth_check -->|"requests shop data"| node_api_client
node_store_setup -->|"requests settings"| node_api_client
node_tracking_compliance -->|"requests policies"| node_api_client
node_store_setup -->|"uses pagination"| node_query_helpers
node_tracking_compliance -->|"uses error handling"| node_query_helpers
node_collector -->|"writes results"| node_output_writer
node_collector -->|"formats summaries"| node_clickup_docs
node_output_writer -->|"writes JSON and Markdown"| node_audit_files
node_clickup_docs -->|"generates summaries"| node_audit_files
node_shopify -->|"serves GraphQL data"| node_api_client
node_operator -->|"reviews app inventory"| node_manual_review
node_manual_review -->|"checks admin settings"| node_shopify

click node_oauth_cli "https://github.com/limesharp/shopify-onboarding/blob/main/src/auth.ts"
click node_relay "https://github.com/limesharp/shopify-onboarding/blob/main/src/relay.ts"
click node_token_exchange "https://github.com/limesharp/shopify-onboarding/blob/main/src/auth.ts"
click node_env_writer "https://github.com/limesharp/shopify-onboarding/blob/main/src/env-writer.ts"
click node_store_config "https://github.com/limesharp/shopify-onboarding/blob/main/src/config.ts"
click node_token_refresh "https://github.com/limesharp/shopify-onboarding/blob/main/src/token-refresh.ts"
click node_collector "https://github.com/limesharp/shopify-onboarding/blob/main/src/index.ts"
click node_api_client "https://github.com/limesharp/shopify-onboarding/blob/main/src/client.ts"
click node_auth_check "https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/auth-check.ts"
click node_store_setup "https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/store-setup.ts"
click node_query_helpers "https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/helpers.ts"
click node_apps_integrations "https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/apps-and-integrations.ts"
click node_tracking_compliance "https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/tracking-compliance.ts"
click node_output_writer "https://github.com/limesharp/shopify-onboarding/blob/main/src/output.ts"
click node_clickup_docs "https://github.com/limesharp/shopify-onboarding/blob/main/src/clickup-doc.ts"
click node_audit_files "https://github.com/limesharp/shopify-onboarding/tree/main/output"

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_oauth_cli,node_relay,node_token_exchange,node_env_writer,node_store_config,node_token_refresh toneBlue
class node_collector,node_api_client,node_auth_check,node_store_setup,node_query_helpers,node_apps_integrations,node_tracking_compliance toneAmber
class node_output_writer,node_clickup_docs,node_audit_files toneMint
class node_shopify,node_manual_review toneRose
class node_operator toneIndigo
```

## Components

### Access and credentials

- [OAuth CLI](https://github.com/limesharp/shopify-onboarding/blob/main/src/auth.ts): `src/auth.ts`
- [OAuth relay](https://github.com/limesharp/shopify-onboarding/blob/main/src/relay.ts): `src/relay.ts`
- [Token exchange](https://github.com/limesharp/shopify-onboarding/blob/main/src/auth.ts): `src/auth.ts`
- [Environment writer](https://github.com/limesharp/shopify-onboarding/blob/main/src/env-writer.ts): `src/env-writer.ts`
- [Store configuration](https://github.com/limesharp/shopify-onboarding/blob/main/src/config.ts): `src/config.ts`
- [Token refresh](https://github.com/limesharp/shopify-onboarding/blob/main/src/token-refresh.ts): `src/token-refresh.ts`

### Audit collection

- [Multi-store runner](https://github.com/limesharp/shopify-onboarding/blob/main/src/index.ts): `src/index.ts`
- [Admin API client](https://github.com/limesharp/shopify-onboarding/blob/main/src/client.ts): `src/client.ts`
- [Connectivity check](https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/auth-check.ts): `src/queries/auth-check.ts`
- [Store setup queries](https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/store-setup.ts): `src/queries/store-setup.ts`
- [Query helpers](https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/helpers.ts): `src/queries/helpers.ts`
- [Apps and integrations](https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/apps-and-integrations.ts): `src/queries/apps-and-integrations.ts`
- [Tracking and compliance](https://github.com/limesharp/shopify-onboarding/blob/main/src/queries/tracking-compliance.ts): `src/queries/tracking-compliance.ts`

### Audit outputs

- [JSON writer](https://github.com/limesharp/shopify-onboarding/blob/main/src/output.ts): `src/output.ts`
- [ClickUp documents](https://github.com/limesharp/shopify-onboarding/blob/main/src/clickup-doc.ts): `src/clickup-doc.ts`
- [Audit files](https://github.com/limesharp/shopify-onboarding/tree/main/output): `output`

### External systems

- **Shopify stores**
- **Manual app review**

### Other components

- **Operator**

## Connections

- Operator → OAuth CLI: starts authorization (evidence: `README.md`)
- OAuth CLI → OAuth relay: polls for code (evidence: `src/auth.ts`)
- Shopify stores → OAuth relay: approves installation (evidence: `README.md`)
- OAuth CLI → Token exchange: exchanges code (evidence: `src/auth.ts`)
- Token exchange → Shopify stores: requests token (evidence: `src/auth.ts`)
- OAuth CLI → Environment writer: saves credentials (evidence: `src/auth.ts`)
- Token refresh → Environment writer: persists refreshed tokens (evidence: `src/token-refresh.ts`)
- Operator → Multi-store runner: runs collection (evidence: `README.md`)
- Multi-store runner → Store configuration: loads stores (evidence: `src/index.ts`)
- Multi-store runner → Token refresh: refreshes tokens (evidence: `src/index.ts`)
- Multi-store runner → Admin API client: builds client (evidence: `src/index.ts`)
- Multi-store runner → Connectivity check: verifies access (evidence: `src/index.ts`)
- Multi-store runner → Store setup queries: collects setup (evidence: `src/index.ts`)
- Multi-store runner → Apps and integrations: runs section (evidence: `src/index.ts`)
- Multi-store runner → Tracking and compliance: collects compliance (evidence: `src/index.ts`)
- Connectivity check → Admin API client: requests shop data (evidence: `src/queries/auth-check.ts`)
- Store setup queries → Admin API client: requests settings (evidence: `src/queries/store-setup.ts`)
- Tracking and compliance → Admin API client: requests policies (evidence: `src/queries/tracking-compliance.ts`)
- Store setup queries → Query helpers: uses pagination (evidence: `src/queries/store-setup.ts`)
- Tracking and compliance → Query helpers: uses error handling (evidence: `src/queries/tracking-compliance.ts`)
- Multi-store runner → JSON writer: writes results (evidence: `src/index.ts`)
- Multi-store runner → ClickUp documents: formats summaries (evidence: `src/index.ts`)
- JSON writer → Audit files: writes JSON and Markdown (evidence: `README.md`)
- ClickUp documents → Audit files: generates summaries (evidence: `README.md`)
- Shopify stores → Admin API client: serves GraphQL data (evidence: `README.md`)
- Operator → Manual app review: reviews app inventory (evidence: `README.md`)
- Manual app review → Shopify stores: checks admin settings (evidence: `README.md`)