# shopify/shopify-app-template-extension-only architecture

> Architecture diagram of the GitHub repository shopify/shopify-app-template-extension-only, 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/shopify/shopify-app-template-extension-only
- Repository: https://github.com/shopify/shopify-app-template-extension-only

## Overview

This is an extension-only Shopify app template: merchants manage FAQ metaobjects in an embedded App Home, while registered app tools expose FAQ listing and retrieval. The FAQ model performs direct browser-side Admin GraphQL reads and writes and maintains a small priming cache; Shopify metaobjects are the persistent store. README documents managed installation and direct API access. The sampled source shows the main routes and data calls; settings is a placeholder, and no storefront FAQ renderer is present in the tree.

Main entry points: [`extensions/app-home/src/AppHome.jsx`](https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/AppHome.jsx) (App Home Router), [`shared/models/faq.ts`](https://github.com/shopify/shopify-app-template-extension-only/blob/main/shared/models/faq.ts) (FAQ Model), [`extensions/app-home/src/pages/HomePage.jsx`](https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/pages/HomePage.jsx) (FAQ List), [`extensions/app-tools/src/index.js`](https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-tools/src/index.js) (FAQ Tool Registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_home["Embedded App Home"]
  node_app_home["App Home Router<br/>[AppHome.jsx]"]
  node_home_page["FAQ List<br/>[HomePage.jsx]"]
  node_faq_page["FAQ Editor<br/>[FaqPage.jsx]"]
  node_settings_page["Settings Page<br/>[SettingsPage.jsx]"]
  node_not_found["Not Found Page<br/>[NotFoundPage.jsx]"]
end

subgraph group_faqdata["FAQ Data"]
  node_faq_model["FAQ Model<br/>[faq.ts]"]
  node_gid_utils["GID Conversion<br/>[gid.ts]"]
end

subgraph group_tools["App Tools"]
  node_tools_extension["FAQ Tool Registration<br/>[index.js]"]
end

subgraph group_shopify["Shopify Services"]
  node_faq_store[("FAQ Metaobjects<br/>[shopify.app.toml]")]
  node_admin_api["Admin GraphQL API"]
  node_managed_install["Managed Installation"]
end

node_merchant(("Merchant"))
node_ai_client(("Tool Client"))

node_merchant -->|"uses embedded app"| node_app_home
node_app_home -->|"routes to"| node_home_page
node_app_home -->|"routes to"| node_faq_page
node_app_home -->|"routes to"| node_settings_page
node_app_home -->|"routes to"| node_not_found
node_home_page -->|"lists FAQs"| node_faq_model
node_home_page -->|"converts IDs"| node_gid_utils
node_faq_page -->|"reads and saves"| node_faq_model
node_faq_model -->|"converts IDs"| node_gid_utils
node_faq_model -->|"queries and mutates"| node_admin_api
node_admin_api -->|"reads and writes"| node_faq_store
node_managed_install -->|"authenticates access"| node_app_home
node_ai_client -.->|"invokes tools"| node_tools_extension
node_tools_extension -->|"lists and fetches"| node_faq_model
node_tools_extension -->|"converts IDs"| node_gid_utils

click node_app_home "https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/AppHome.jsx"
click node_home_page "https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/pages/HomePage.jsx"
click node_faq_page "https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/pages/FaqPage.jsx"
click node_settings_page "https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/pages/SettingsPage.jsx"
click node_not_found "https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/pages/NotFoundPage.jsx"
click node_faq_model "https://github.com/shopify/shopify-app-template-extension-only/blob/main/shared/models/faq.ts"
click node_gid_utils "https://github.com/shopify/shopify-app-template-extension-only/blob/main/shared/utils/gid.ts"
click node_faq_store "https://github.com/shopify/shopify-app-template-extension-only/blob/main/shopify.app.toml"
click node_tools_extension "https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-tools/src/index.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_home,node_home_page,node_faq_page,node_settings_page,node_not_found,node_ai_client toneBlue
class node_faq_model,node_gid_utils toneAmber
class node_tools_extension toneMint
class node_faq_store,node_admin_api,node_managed_install toneRose
class node_merchant toneIndigo
```

## Components

### Embedded App Home

- [App Home Router](https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/AppHome.jsx): `extensions/app-home/src/AppHome.jsx`
- [FAQ List](https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/pages/HomePage.jsx): `extensions/app-home/src/pages/HomePage.jsx`
- [FAQ Editor](https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/pages/FaqPage.jsx): `extensions/app-home/src/pages/FaqPage.jsx`
- [Settings Page](https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/pages/SettingsPage.jsx): `extensions/app-home/src/pages/SettingsPage.jsx`
- [Not Found Page](https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-home/src/pages/NotFoundPage.jsx): `extensions/app-home/src/pages/NotFoundPage.jsx`

### FAQ Data

- [FAQ Model](https://github.com/shopify/shopify-app-template-extension-only/blob/main/shared/models/faq.ts): `shared/models/faq.ts`
- [GID Conversion](https://github.com/shopify/shopify-app-template-extension-only/blob/main/shared/utils/gid.ts): `shared/utils/gid.ts`

### App Tools

- [FAQ Tool Registration](https://github.com/shopify/shopify-app-template-extension-only/blob/main/extensions/app-tools/src/index.js): `extensions/app-tools/src/index.js`

### Shopify Services

- [FAQ Metaobjects](https://github.com/shopify/shopify-app-template-extension-only/blob/main/shopify.app.toml): `shopify.app.toml`
- **Admin GraphQL API**
- **Managed Installation**

### Other components

- **Merchant**
- **Tool Client**

## Connections

- Merchant → App Home Router: uses embedded app (evidence: `README.md`)
- App Home Router → FAQ List: routes to (evidence: `extensions/app-home/src/AppHome.jsx`)
- App Home Router → FAQ Editor: routes to (evidence: `extensions/app-home/src/AppHome.jsx`)
- App Home Router → Settings Page: routes to (evidence: `extensions/app-home/src/AppHome.jsx`)
- App Home Router → Not Found Page: routes to (evidence: `extensions/app-home/src/AppHome.jsx`)
- FAQ List → FAQ Model: lists FAQs (evidence: `extensions/app-home/src/pages/HomePage.jsx`)
- FAQ List → GID Conversion: converts IDs (evidence: `extensions/app-home/src/pages/HomePage.jsx`)
- FAQ Editor → FAQ Model: reads and saves (evidence: `extensions/app-home/src/pages/FaqPage.jsx`)
- FAQ Model → GID Conversion: converts IDs (evidence: `shared/models/faq.ts`)
- FAQ Model → Admin GraphQL API: queries and mutates (evidence: `shared/models/faq.ts`)
- Admin GraphQL API → FAQ Metaobjects: reads and writes (evidence: `README.md`)
- Managed Installation → App Home Router: authenticates access (evidence: `README.md`)
- Tool Client → FAQ Tool Registration: invokes tools
- FAQ Tool Registration → FAQ Model: lists and fetches (evidence: `extensions/app-tools/src/index.js`)
- FAQ Tool Registration → GID Conversion: converts IDs (evidence: `extensions/app-tools/src/index.js`)
