# shopify/shopify_app architecture

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

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

## Overview

- Frontend Integration & Embedded UI: Although the gem itself isn’t a full front-end application, it supplies assets and embedded app layouts (e.g., the embedded_app layout, app/assets/javascripts, and related partials) that the host Rails app will render inside Shopify’s admin.
- Rails Engine & Routing: Emphasize the Shopify App Rails engine that mounts its own routes (e.g., /login, /auth/shopify/callback, /logout, /webhooks/:type). Include a separate “Engine” component that handles OAuth and session management.
- OAuth & Authentication Workflow: Show how the gem facilitates OAuth flows via controllers (e.g., authenticated_controller, sessions_controller, callback_controller) and uses session tokens for authentication. Mark the transition from initial login → OAuth callback → post-authentication tasks (including token exchange and script tag handling).
- Job Processing & Background Tasks: Include components for handling background jobs (e.g., webhooks_manager_job, script_tags_manager_job, rotate_shopify_token_job) that manage asynchronous API calls and webhook processing.
- Session & State Management: Indicate the session handling layer provided in lib/shopify_app/session (with different strategies for shop and user sessions) that supports the use of in-memory or persistent session stores.
- API Communication: Represent the integration with Shopify’s APIs through modules in lib/shopify_app/admin_api and token exchange mechanisms in lib/shopify_app/auth, highlighting how access tokens are managed and refreshed.
- Testing & Documentation: Consider a separate block summarizing the test suite and documentation components which ensure the system’s robustness and provide implementation guidance. Although not part of the runtime, these components underline the design’s reliability.

##### Interrelationships and interactions
- A request from the embedded Shopify admin app → reaches the login or OAuth route.
- The OAuth callback is handled by the Shopify App engine’s callback controller.
- Post-authentication tasks (using token exchange strategies and post-authenticate tasks) complete the handshake.
- Link the generator commands (invoked by developers during app setup) to the scaffolding mechanism that integrates controllers, views, and the underlying database migrations.
- How controller concerns (such as CSRF protection, billing, and webhook verification) are mixed into various controller components, and then connect these to job handlers that asynchronously process requests (such as webhook notifications).

##### Important architectural/design patterns
- Use of the Rails Engine pattern to encapsulate the Shopify-specific functionality.
- Separation of concerns via mixins/concerns for authentication, session management, and webhook processing.
- Mention the extensibility provided by generators, which follow the convention over configuration paradigm of Rails.
- Dependency on external configuration (via environment variables, the Shopify Partners account, and initializers like config/initializers/shopify_app.rb).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    SC["Shopify Admin (Client)"]:::external
    DEV["Developer"]:::external
    SAPI["Shopify Platform API"]:::external

    %% Enhanced Rails App (Container)
    subgraph "Enhanced Rails App"
        
        %% Frontend Integration & Embedded UI
        subgraph "Frontend Integration & Embedded UI"
            FE1["Embedded App Layouts & Assets"]:::frontend
            FE1A["Assets"]:::frontend
            FE1B["Layouts & Partials"]:::frontend
        end

        %% Rails Engine & Routing
        subgraph "Rails Engine & Routing"
            RE1["Rails Engine"]:::engine
            RE2["Routing"]:::engine
        end

        %% OAuth & Authentication Workflow
        subgraph "OAuth & Authentication Workflow"
            OA1["Sessions Controller"]:::auth
            OA2["Callback Controller"]:::auth
            OA3["Authenticated Controller"]:::auth
            OA4["Extension Verification Controller"]:::auth
            OA5["Controller Concerns"]:::auth
        end

        %% Generators & Application Scaffolding
        subgraph "Generators & Application Scaffolding"
            GEN1["Generators & Scaffolding"]:::generator
        end

        %% Job Processing & Background Tasks
        subgraph "Job Processing & Background Tasks"
            JOB1["Background Jobs"]:::jobs
        end

        %% Session & State Management
        subgraph "Session & State Management"
            SM1["Session Management"]:::session
        end

        %% API Communication
        subgraph "API Communication"
            API1["Admin API Integration"]:::api
            API2["OAuth Token Exchange"]:::api
        end

        %% Testing & Documentation
        subgraph "Testing & Documentation"
            DOC1["Testing & Documentation"]:::test
        end
    end

    %% Connections / Data Flows
    SC -->|"initiates"| FE1
    FE1A --> FE1
    FE1B --> FE1
    FE1 -->|"renders into"| RE1
    RE2 -->|"routes to"| OA1
    RE2 -->|"routes to"| OA2
    RE2 -->|"routes to"| OA3
    RE2 -->|"routes to"| OA4

    OA1 -->|"triggers OAuth"| OA2
    OA2 -->|"exchanges token"| API2
    API2 -->|"communicates with"| API1
    OA1 -->|"uses"| SM1
    OA3 -->|"uses"| SM1
    OA4 -->|"uses"| SM1

    RE2 -->|"dispatches webhooks"| JOB1

    DEV -->|"runs"| GEN1

    %% External API Call from Rails Engine
    RE1 -->|"calls"| SAPI

    %% Styles for clarity of data flow
    class SC,DEV,SAPI external

    %% Click Events
    click FE1A "https://github.com/shopify/shopify_app/blob/main/app/assets/javascripts/shopify_app/redirect.js"
    click FE1B "https://github.com/shopify/shopify_app/blob/main/app/views/shopify_app/layouts/app_bridge.html.erb"
    click RE1 "https://github.com/shopify/shopify_app/blob/main/lib/shopify_app/engine.rb"
    click RE2 "https://github.com/shopify/shopify_app/blob/main/config/routes.rb"
    click OA1 "https://github.com/shopify/shopify_app/blob/main/app/controllers/shopify_app/sessions_controller.rb"
    click OA2 "https://github.com/shopify/shopify_app/blob/main/app/controllers/shopify_app/callback_controller.rb"
    click OA3 "https://github.com/shopify/shopify_app/blob/main/app/controllers/shopify_app/authenticated_controller.rb"
    click OA4 "https://github.com/shopify/shopify_app/blob/main/app/controllers/shopify_app/extension_verification_controller.rb"
    click OA5 "https://github.com/shopify/shopify_app/blob/main/app/controllers/concerns/shopify_app/ensure_authenticated_links.rb"
    click GEN1 "https://github.com/shopify/shopify_app/tree/main/lib/generators/shopify_app"
    click JOB1 "https://github.com/shopify/shopify_app/blob/main/lib/shopify_app/jobs/script_tags_manager_job.rb"
    click SM1 "https://github.com/shopify/shopify_app/tree/main/lib/shopify_app/session"
    click API1 "https://github.com/shopify/shopify_app/tree/main/lib/shopify_app/admin_api"
    click API2 "https://github.com/shopify/shopify_app/blob/main/lib/shopify_app/auth/token_exchange.rb"
    click DOC1 "https://github.com/shopify/shopify_app/tree/main/docs/shopify_app"

    %% Class Definitions
    classDef frontend fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef engine fill:#ABEBC6,stroke:#229954,stroke-width:2px;
    classDef auth fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef generator fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef jobs fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef session fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef api fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef test fill:#CCD1D1,stroke:#7F8C8D,stroke-width:2px;
    classDef external fill:#FDEBD0,stroke:#F39C12,stroke-width:2px;
```
