# contentstack/marketplace-app-boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/contentstack/marketplace-app-boilerplate
- Repository: https://github.com/contentstack/marketplace-app-boilerplate

## Overview

##### Main components
- Entry Point & Client-Side Bootstrapping:
- Public folder (which contains index.html and manifest files) as the static assets.
- Src/index.tsx as the application’s entry point that loads the root React application.
- Core Application Container:
- Main App container (src/containers/App/App.tsx) which coordinates the application’s routing and lazy loading of different route components.
- MarketplaceAppProvider:
- <MarketplaceAppProvider> that wraps the application. This provider is responsible for initializing the Contentstack SDK, setting up global properties (like analytics and error tracking), and exposing the SDK via hooks.
- Context Providers & Hooks:
- Various context providers (found in src/common/contexts and src/common/providers) for different extension types such as AppConfigurationExtensionProvider, CustomFieldExtensionProvider, and EntrySidebarExtensionProvider. Their role is to supply extension-specific configurations throughout the component tree.
- Additionally, emphasize the usage of custom hooks (e.g., useAppConfig, useAppSdk, useCustomField, etc.) which are part of the application’s bridging logic between the SDK and UI.
- Route Components and Lazy Loading:
- UI Components & Containers:
- “components” and “containers” directories which hold individual UI components (like ErrorBoundary, ConfigModal, Sidebars, and Tooltips). They are arranged to form the various visual and interactive parts of the application.
- Testing and Development Tools:
- Testing suite components:
o The “e2e” folder which contains end-to-end tests (illustrate pages, tests, and utility functions used by Playwright).
o The “src/__tests__” folder (unit and integration tests).
- Build and configuration files (e.g., package.json, tsconfig.json, playwright.config.ts) as external dependencies that ensure proper building and testing.

##### Relationships and interactions
- That the App container routes different paths to lazily loaded components, which in turn depend on context providers and hooks to receive data and configuration.
- Interactions between UI components and backend services (if applicable), indicating that the Contentstack SDK is used as the middleware between the UI and Contentstack’s service endpoints.

##### Important architectural patterns and design principles
- The Provider Pattern: Used extensively for dependency injection (Contentstack SDK and extension contexts).
- Lazy Loading of Routes: As described in the README, to optimize performance.
- Separation of Concerns: The project structure clearly separates static assets, configuration, hooks, providers, UI components, and test suites.
- Component Reusability: Through custom hooks and context providers which reduce props drilling by exposing SDK data directly to components.

##### Relevant technologies and frameworks
- React for building the UI.
- Playwright for end-to-end testing.
- TypeScript for type safety.
- ESLint, Prettier, and other configuration tools to maintain code quality.
- Basic CSS for styling alongside modular CSS files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry & Bootstrapping
    subgraph "Entry & Bootstrapping"
        E1("public/index.html") 
        E2("public/manifest.json")
        E3("Entry Point (src/index.tsx)")
    end

    %% Core Application Container
    subgraph "Core Application"
        A("App Container (src/containers/App/App.tsx)")
    end

    %% Providers
    subgraph "Providers"
        P1("MarketplaceAppProvider (src/common/providers/MarketplaceAppProvider.tsx)")
        CP1("AppConfigurationExtensionProvider (src/common/providers/AppConfigurationExtensionProvider.tsx)")
        CP2("CustomFieldExtensionProvider (src/common/providers/CustomFieldExtensionProvider.tsx)")
        CP3("EntrySidebarExtensionProvider (src/common/providers/EntrySidebarExtensionProvider.tsx)")
        CP4("Marketplace Context (src/common/contexts/marketplaceContext.ts)")
    end

    %% Custom Hooks
    subgraph "Custom Hooks"
        H1("useAppConfig (src/common/hooks/useAppConfig.ts)")
        H2("useAppSdk (src/common/hooks/useAppSdk.tsx)")
        H3("useCustomField (src/common/hooks/useCustomField.tsx)")
    end

    %% Routes & Lazy Loading
    subgraph "Routes & Lazy Loading"
        R1("CustomField Route (src/containers/CustomField/)")
        R2("AssetSidebarWidget Route (src/containers/AssetSidebarWidget/)")
    end

    %% UI Components & Containers
    subgraph "UI Components & Containers"
        UI1("UI Components (src/components/)")
        UI2("Additional Containers (src/containers/)")
    end

    %% Testing & Configuration
    subgraph "Testing & Config"
        T1("e2e Tests (e2e/)")
        T2("Unit/Integration Tests (src/test-utils/test-utils.tsx)")
        T3("Build & Config Files (package.json, tsconfig.json, playwright.config.ts, global-setup.ts, global-teardown.ts)")
    end

    %% Connections / Data Flow
    E3 -->|"bootstraps"| A
    A -->|"wrapped by"| P1
    P1 --> CP1
    P1 --> CP2
    P1 --> CP3
    P1 --> CP4
    CP1 -->|"exposes"| H1
    CP2 -->|"exposes"| H2
    CP3 -->|"exposes"| H3
    H1 -->|"feeds"| UI1
    H2 --> UI1
    H3 --> UI1
    A -->|"defines"| R1
    A --> R2
    R1 -->|"renders"| UI2
    R2 --> UI2
    A -->|"tested by"| T1
    A --> T2
    A --> T3

    %% Click Events
    click E1 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/public/index.html"
    click E2 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/public/manifest.json"
    click E3 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/index.tsx"
    click A "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/containers/App/App.tsx"
    click P1 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/common/providers/MarketplaceAppProvider.tsx"
    click CP1 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/common/providers/AppConfigurationExtensionProvider.tsx"
    click CP2 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/common/providers/CustomFieldExtensionProvider.tsx"
    click CP3 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/common/providers/EntrySidebarExtensionProvider.tsx"
    click CP4 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/common/contexts/marketplaceContext.ts"
    click H1 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/common/hooks/useAppConfig.ts"
    click H2 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/common/hooks/useAppSdk.tsx"
    click H3 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/common/hooks/useCustomField.tsx"
    click R1 "https://github.com/contentstack/marketplace-app-boilerplate/tree/main/src/containers/CustomField/"
    click R2 "https://github.com/contentstack/marketplace-app-boilerplate/tree/main/src/containers/AssetSidebarWidget/"
    click UI1 "https://github.com/contentstack/marketplace-app-boilerplate/tree/main/src/components/"
    click UI2 "https://github.com/contentstack/marketplace-app-boilerplate/tree/main/src/containers/"
    click T1 "https://github.com/contentstack/marketplace-app-boilerplate/tree/main/e2e/"
    click T2 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/src/test-utils/test-utils.tsx"
    click T3 "https://github.com/contentstack/marketplace-app-boilerplate/blob/main/package.json"

    %% Styles
    class E1,E2,E3 entry
    class A app
    class P1,CP1,CP2,CP3,CP4 provider
    class H1,H2,H3 hook
    class R1,R2 route
    class UI1,UI2 ui
    class T1,T2,T3 test

    %% Class Definitions
    classDef entry fill:#ffffcc,stroke:#000,stroke-width:2px;
    classDef app fill:#cce5ff,stroke:#000,stroke-width:2px;
    classDef provider fill:#e0f7fa,stroke:#000,stroke-width:2px,stroke-dasharray: 5,5;
    classDef hook fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef route fill:#e6ccff,stroke:#000,stroke-width:2px;
    classDef ui fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef test fill:#ffcccc,stroke:#000,stroke-width:2px,stroke-dasharray: 2,2;
```
