# SOLID Design Principles - Coding Assistant Guidelines

  When generating, reviewing, or modifying code, follow these guidelines to ensure adherence to SOLID principles:

## 1. Single Responsibility Principle (SRP)

  - Each class must have only one reason to change.
  - Limit class scope to a single functional area or abstraction level.
  - When a class exceeds 100-150 lines, consider if it has multiple responsibilities.
  - Separate cross-cutting concerns (logging, validation, error handling) from business logic.
  - Create dedicated classes for distinct operations like data access, business rules, and UI.
  - Method names should clearly indicate their singular purpose.
  - If a method description requires "and" or "or", it likely violates SRP.
  - Prioritize composition over inheritance when combining behaviors.

## 2. Open/Closed Principle (OCP)

  - Design classes to be extended without modification.
  - Use abstract classes and interfaces to define stable contracts.
  - Implement extension points for anticipated variations.
  - Favor strategy patterns over conditional logic.
  - Use configuration and dependency injection to support behavior changes.
  - Avoid switch/if-else chains based on type checking.
  - Provide hooks for customization in frameworks and libraries.
  - Design with polymorphism as the primary mechanism for extending functionality.

## 3. Liskov Substitution Principle (LSP)

  - Ensure derived classes are fully substitutable for their base classes.
  - Maintain all invariants of the base class in derived classes.
  - Never throw exceptions from methods that don't specify them in base classes.
  - Don't strengthen preconditions in subclasses.
  - Don't weaken postconditions in subclasses.
  - Never override methods with implementations that do nothing or throw exceptions.
  - Avoid type checking or downcasting, which may indicate LSP violations.
  - Prefer composition over inheritance when complete substitutability can't be achieved.

## 4. Interface Segregation Principle (ISP)

  - Create focused, minimal interfaces with cohesive methods.
  - Split large interfaces into smaller, more specific ones.
  - Design interfaces around client needs, not implementation convenience.
  - Avoid "fat" interfaces that force clients to depend on methods they don't use.
  - Use role interfaces that represent behaviors rather than object types.
  - Implement multiple small interfaces rather than a single general-purpose one.
  - Consider interface composition to build up complex behaviors.
  - Remove any methods from interfaces that are only used by a subset of implementing classes.

## 5. Dependency Inversion Principle (DIP)

  - High-level modules should depend on abstractions, not details.
  - Make all dependencies explicit, ideally through constructor parameters.
  - Use dependency injection to provide implementations.
  - Program to interfaces, not concrete classes.
  - Place abstractions in a separate package/namespace from implementations.
  - Avoid direct instantiation of service classes with 'new' in business logic.
  - Create abstraction boundaries at architectural layer transitions.
  - Define interfaces owned by the client, not the implementation.

## Implementation Guidelines

  - When starting a new class, explicitly identify its single responsibility.
  - Document extension points and expected subclassing behavior.
  - Write interface contracts with clear expectations and invariants.
  - Question any class that depends on many concrete implementations.
  - Use factories, dependency injection, or service locators to manage dependencies.
  - Review inheritance hierarchies to ensure LSP compliance.
  - Regularly refactor toward SOLID, especially when extending functionality.
  - Use design patterns (Strategy, Decorator, Factory, Observer, etc.) to facilitate SOLID adherence.

## Warning Signs

  - God classes that do "everything"
  - Methods with boolean parameters that radically change behavior
  - Deep inheritance hierarchies
  - Classes that need to know about implementation details of their dependencies
  - Circular dependencies between modules
  - High coupling between unrelated components
  - Classes that grow rapidly in size with new features
  - Methods with many parameters

## Core Principles:
  - Optimize for Hydrogens **streaming and caching** model to enhance performance.
  - Use **Shopifys Storefront API** effectively, following best practices for queries and mutations.
  - Ensure all components are **server-first** but leverage **client-side hydration** where needed.
  - Use **Tailwind CSS** efficiently with Hydrogens best practices for styling.
  - Prioritize **authentication and session handling** for Shopify customers.

## Routing & Layout in Remix
  - Use `loader` functions for **server-side data fetching**.
  - Prefer **nested routes** for modular page structures.
  - Use `useLoaderData()` instead of client-side fetching where possible.
  - Optimize Remixs **deferred loading** to improve perceived performance.

## Shopify Storefront API Usage
  - Always fetch data using **GraphQL queries** in `loader` functions.
  - Minimize API requests by batching queries efficiently.
  - Cache queries where appropriate to **reduce unnecessary API calls**.
  - Avoid over-fetching request **only the necessary fields**.
  - Use Shopifys **recommended pagination techniques** (`cursor`-based pagination).

## Hydrogen & Performance Optimizations
  - Utilize **Hydrogens streaming API** to improve time-to-first-byte (TTFB).
  - Use `CacheNone()` or `CacheLong()` selectively to control caching behavior.
  - Edge caching Ensure frequently accessed data is cached at the CDN level.
  - Prefer `useShopQuery()` over manual API calls for **consistent data fetching**.
  - Offload **expensive computations to server-side** where possible.

## Styling & Tailwind CSS
  - Use **Hydrogens built-in Tailwind setup** for consistency.
  - Avoid excessive utility classes by leveraging **Tailwinds theme and variants**.
  - Structure styles efficiently to **minimize CSS bloat**.
  - Use **Tailwinds responsive utilities** to ensure a mobile-first approach.

## Authentication & Session Handling
  - Implement Shopifys **customer authentication** using `customerAccessToken`.
  - Store authentication tokens securely in **server-side sessions**.
  - Use Remix loaders and actions to **handle login and logout server-side**.
  - Ensure **session expiry is handled gracefully** to prevent errors.
  - Implement **SSR-friendly authentication checks** to avoid hydration mismatches.

## Deployment on Shopify Oxygen
  - Follow **Shopifys guidelines for edge deployment**.
  - Ensure **Remix server handlers** are optimized for Oxygen.
  - Use `@shopify/hydrogen` utilities for **seamless integration with Shopify's infrastructure**.
  - Test deployments using Shopifys **Oxygen preview environment** before production.

## Component & Code Best Practices
  - Prefer **server components** whenever possible to reduce client-side JavaScript.
  - Use **lazy loading** (`React.lazy()`, `Suspense`) for non-critical UI components.
  - Keep components **small, modular, and reusable**.
  - Avoid excessive **client-side state management**; leverage Remix loaders instead.
  - Use **React Error Boundaries** for graceful error handling.

## Key Conventions:
  - Always **fetch data in loaders**; minimize client-side API calls.
  - Structure routes **to take full advantage of Remixs nested routing**.
  - Use **server caching strategies** to reduce redundant Storefront API calls.
  - Optimize **Hydrogens streaming features** for a fast user experience.
  - Follow **Shopifys best practices for deployment on Oxygen**.

Refer to Shopifys Hydrogen and Remix documentation for additional best practices.

Create a persistent cart component in Hydrogen that maintains state across page reloads.
- Ensure the cart syncs with Shopifys Storefront API.
- Implement local storage or session storage for offline persistence.
- Support add, update, and remove item actions with real-time UI updates.
- Handle quantity updates and display cart subtotal dynamically.
- Use React state management (useState or useReducer) for cart logic.
- Optimize performance by debouncing API calls for quantity changes.

Given the following component requirement, generate a Hydrogen-compatible implementation that adheres to Shopify's framework constraints and best practices.

**Requirement:** {Provide a brief description of the component, e.g., "a button that adds an item to the cart and redirects to checkout."}

**Instructions:**
- Identify the correct Shopify API or module needed (e.g., Storefront API, Cart API, Checkout API).
- Ensure the implementation follows Shopifys best practices and rate limits.
- Use only the necessary logic and avoid overengineering.
- Validate that the feature works within Shopify's React/Hydrogen ecosystem.
- Return a concise and properly structured React component.
- If a feature is **not possible** due to Shopify constraints, explain why and suggest an alternative.

**Example Input:**
"A button that adds an item to the cart and redirects to checkout."

**Example Output:**
- Uses Shopifys `cartCreate` mutation for adding items.
- Implements Shopifys `useNavigate()` for redirection.
- Provides necessary error handling for API failures.
- Ensures UI feedback (loading state, error message) is included.

**Now, generate the implementation based on the provided requirement.**

Create a Hydrogen routing strategy that dynamically loads Shopify CMS content based on URL structure.

- Use Shopifys Storefront API to fetch dynamic content (e.g., pages, blogs, collections).
- Implement Remix loaders to prefetch CMS content efficiently.
- Ensure the routing structure follows Shopifys best practices for SEO-friendly URLs.
- Handle dynamic slugs (e.g., `/blog/{article-handle}` or `/pages/{page-handle}`).
- Optimize page performance by caching frequently accessed content.
- Provide fallback handling for non-existent or unpublished content.

Set up Shopify OAuth authentication in Hydrogen for secure customer logins.

- Check if Shopify provides built-in authentication components and use them if available.
- If authentication components are not provided, set up basic login UI (email/password input, OAuth login button).
- Use Shopifys `customerAccessTokenCreate` mutation to handle authentication.
- Store the access token securely (e.g., session storage, HTTP-only cookies).
- Implement a logout function using `customerAccessTokenDelete`.
- Set up authentication context or state management to persist user session.
- Ensure authenticated routes restrict access to logged-in users.
- Handle error states (e.g., invalid login, expired tokens) with proper UI feedback.