How shopify/shopify_app works
• 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).