# contentful/apps architecture

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

- Interactive diagram: https://gitdiagram.com/contentful/apps
- Repository: https://github.com/contentful/apps

## Overview

##### Project type and purpose
- This is a large monorepo (“apps” + “packages” + “scripts”) containing multiple Contentful Marketplace apps (React front‐ends, serverless back‐ends, and shared libraries).
- It’s managed with Lerna/Nx (see lerna.json, nx.json) and contains CI/CD configurations (.circleci/, .github/workflows).

##### Structure and extract main components
- Monorepo Root
– Package manager & orchestrators (package.json, lerna.json, nx.json).
– CI/CD pipelines (.circleci/config.yml, GitHub workflows).
– Scripts (scripts/… for provisioning Contentful spaces, apps, etc.).
- Shared Libraries (packages/)
– dam-app-base
– ecommerce-app-base
– eslint-plugin-contentful-apps
These are npm packages consumed by individual apps.
- Apps (apps/)
By pattern:
– UI-only (e.g. ai-content-generator, aws-amplify, bulk-edit): React-based front-ends loaded in the Contentful web app.
– Front-end + serverless back-end (e.g. ai-image-generator, google-analytics-4, slack):
- Front-end (apps/<app>/frontend or apps/<app>/src): Vite/React, Contentful App SDK.
- Serverless functions (apps/<app>/backend or apps/<app>/lambda): handlers keyed to App Actions or App Events, deployed via Serverless framework/Docker.
– Examples of external service clients in services/ or utils/: OpenAI, AWS Bedrock, Google Analytics, Slack, MS Teams, etc.
- External services
– Contentful Content Management API & App SDK
– Third-party APIs (OpenAI, AWS Bedrock, Google Analytics, Slack, Microsoft Graph, Mux, etc.)

##### Relationships and interactions
- Each app’s front-end is embedded in Contentful’s extension iframe.
- User interactions in the UI call:
– Shared libraries (dam-app-base, ecommerce-app-base).
– Contentful App SDK → CMA or own serverless functions.
- Serverless back-end functions (lambda) handle:
– App actions/events (e.g. generate AI content, upload images).
– Proxy to third-party APIs.
– Persist credentials or usage in a database (e.g. DynamoDB for google-analytics-4, slack).
- CI/CD pipelines run tests (frontend with vitest/jest, backend with Mocha), build bundles, and deploy functions to cloud providers.

##### Key architectural patterns
- Monorepo + Lerna/Nx: centralized dependency management and versioning.
- Modular apps: each app folder is an independent micro-frontend (and optional micro-service).
- Shared UI libraries: base packages reduce duplication across apps.
- Serverless microservices: stateless functions triggered by HTTP (actions) or events, scale on demand.
- Layered separation:
– Presentation: React-based UI loaded in Contentful.
– Business logic: Hooks, utils, providers in front-end.
– Integration layer: Serverless functions & API helpers.
– External systems: CMA, third-party APIs, Databases.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo
    subgraph "Monorepo Root"
        direction TB
        Lerna["lerna.json"]:::tooling
        Nx["nx.json"]:::tooling
        PackageJSON["package.json"]:::tooling
        subgraph "CI/CD Pipelines"
            direction TB
            CircleCI[".circleci/config.yml"]:::tooling
            GitHubWF[".github/workflows/"]:::tooling
        end
        Scripts["scripts/"]:::tooling
    end

    %% Shared Packages
    subgraph "Shared Libraries"
        direction TB
        DamBase["dam-app-base"]:::shared
        EcommerceBase["ecommerce-app-base"]:::shared
        ESLintPlugin["eslint-plugin-contentful-apps"]:::shared
    end

    %% Apps
    subgraph "Apps"
        direction TB
        subgraph "UI-Only Apps"
            direction TB
            BulkEditFE["Bulk-Edit Front-end"]:::frontend
            AWSAmplifyFE["AWS-Amplify Front-end"]:::frontend
        end
        subgraph "Front-end + Serverless Apps"
            direction TB
            subgraph "AI Image Generator"
                direction TB
                AIImageFE["FE: ai-image-generator"]:::frontend
                AIImageBE["BE: ai-image-generator"]:::backend
            end
            subgraph "Google Analytics 4"
                direction TB
                GA4FE["FE: google-analytics-4"]:::frontend
                GA4BE["BE: google-analytics-4"]:::backend
            end
            subgraph "Slack"
                direction TB
                SlackFE["FE: slack"]:::frontend
                SlackBE["BE: slack"]:::backend
            end
        end
    end

    %% Contentful Platform
    subgraph "Contentful Platform"
        direction TB
        AppSDK["App SDK"]:::platform
        CMA["Content Management API"]:::platform
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI / AWS Bedrock"]:::external
        GoogleAnalytics["Google Analytics"]:::external
        SlackService["Slack / MS Teams"]:::external
        Hosting["Mux / Netlify / Vercel"]:::external
    end

    %% Connections
    Lerna -->|manages| DamBase
    Lerna -->|manages| EcommerceBase
    Lerna -->|manages| ESLintPlugin
    Nx -->|orchestrates| BulkEditFE
    Nx -->|orchestrates| AIImageFE

    BulkEditFE -->|imports| DamBase
    AWSAmplifyFE -->|imports| EcommerceBase

    AIImageFE -->|"HTTP call"| AIImageBE
    GA4FE -->|"HTTP call"| GA4BE
    SlackFE -->|"HTTP call"| SlackBE

    AIImageBE -->|"calls API"| OpenAI
    GA4BE -->|"calls API"| GoogleAnalytics
    SlackBE -->|"calls API"| SlackService

    BulkEditFE -->|embedded via SDK| AppSDK
    AIImageFE -->|embedded via SDK| AppSDK

    AppSDK -->|uses| CMA

    CircleCI -->|ci triggers| Lerna
    CircleCI -->|ci triggers| AIImageBE
    GitHubWF -->|ci triggers| SlackFE

    %% Click Events
    click Lerna "https://github.com/contentful/apps/blob/master/lerna.json"
    click Nx "https://github.com/contentful/apps/blob/master/nx.json"
    click PackageJSON "https://github.com/contentful/apps/blob/master/package.json"
    click CircleCI "https://github.com/contentful/apps/blob/master/.circleci/config.yml"
    click GitHubWF "https://github.com/contentful/apps/tree/master/.github/workflows/"
    click Scripts "https://github.com/contentful/apps/tree/master/scripts/"
    click DamBase "https://github.com/contentful/apps/tree/master/packages/dam-app-base/"
    click EcommerceBase "https://github.com/contentful/apps/tree/master/packages/ecommerce-app-base/"
    click ESLintPlugin "https://github.com/contentful/apps/tree/master/packages/eslint-plugin-contentful-apps/"
    click BulkEditFE "https://github.com/contentful/apps/tree/master/apps/bulk-edit/src/"
    click AWSAmplifyFE "https://github.com/contentful/apps/tree/master/apps/aws-amplify/src/"
    click AIImageFE "https://github.com/contentful/apps/tree/master/apps/ai-image-generator/frontend/"
    click AIImageBE "https://github.com/contentful/apps/tree/master/apps/ai-image-generator/backend/"
    click GA4FE "https://github.com/contentful/apps/tree/master/apps/google-analytics-4/frontend/"
    click GA4BE "https://github.com/contentful/apps/tree/master/apps/google-analytics-4/lambda/"
    click SlackFE "https://github.com/contentful/apps/tree/master/apps/slack/frontend/"
    click SlackBE "https://github.com/contentful/apps/tree/master/apps/slack/lambda/"
    click OpenAI "https://github.com/contentful/apps/blob/master/apps/ai-image-generator/backend/src/services/openaiApiService.ts"
    click GoogleAnalytics "https://github.com/contentful/apps/blob/master/apps/google-analytics-4/lambda/src/services/googleApiService.ts"
    click SlackService "https://github.com/contentful/apps/blob/master/apps/slack/lambda/lib/clients/slack.ts"

    %% Styles
    classDef tooling fill:#FFA500,stroke:#333,stroke-width:1px
    classDef shared fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef frontend fill:#98FB98,stroke:#333,stroke-width:1px
    classDef backend fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef platform fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef apps fill:#E0FFE0,stroke:#333,stroke-width:1px
```
