# vtex-apps/admin-catalog-translations architecture

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

- Interactive diagram: https://gitdiagram.com/vtex-apps/admin-catalog-translations
- Repository: https://github.com/vtex-apps/admin-catalog-translations

## Overview

##### Project Type and Purpose
- This is a full-stack VTEX IO admin application called “Admin Catalog Translation.”
- Purpose: Provide UI pages to list, export, import and edit SEO-relevant translations for catalog entities (Category, Product, SKU, Brand, Specification, Collection) across multiple storefront bindings in a VTEX account.

##### File-Structure Analysis
- Top-level:
- manifest.json, service.json, package.json – VTEX IO app manifests and dependency declarations
- .vtexignore, CI config, lint/prettier rules, docs, CHANGELOG
- admin/ – JSON definitions for VTEX IO Admin App navigation and route registration
- node/ – The backend service:
- clients/ – modules wrapping external VTEX GraphQL endpoints (e.g. catalog, catalogGQL)
- resolvers/ – one folder per entity (brand, category, product, sku, collection, field, translation) defining GraphQL resolvers for queries & mutations (.upload.ts, index.ts)
- utils/ – shared helper functions
- react/ – The frontend:
- components/ – per-entity translation pages (forms, import/export modals), plus shared UI (buttons, modal, error handlers, locale selector)
- graphql/ – .gql queries and mutations used by the components
- hooks/, providers/, utils/ – custom React hooks, context providers (alerts), file parsers, sanitation logic
- BrandTranslation.tsx, CategoryTranslation.tsx, etc. – top-level screens
- messages/ & public/metadata – localization resource files for multiple languages
- docs/ – developer documentation

##### Key Architecture Insights from README
- Uses VTEX IO CLI for installation
- Talks to `vtex.catalog-graphql` rather than the messages app to focus on SEO fields
- Each entity page lists storefront bindings; default binding is read-only; other bindings support create/update via GraphQL
- Bulk import/export via CSV/JSON files

a. Main Components
1. Admin UI (React App)
2. VTEX IO GraphQL Gateway (managed by VTEX platform)
3. Node Service (GraphQL resolvers)
4. External VTEX Catalog GraphQL API (`vtex.catalog-graphql`)
5. Static Assets & Localization (public/metadata + messages)

b. Relationships & Data Flows
- User interacts with React UI in the Admin Console.
- React components invoke GraphQL operations against the VTEX IO GraphQL Gateway.
- Gateway routes queries/mutations to the Node Service.
- Node Service resolvers use internal clients to call the external `vtex.catalog-graphql` API for read/write on catalog data.
- Node Service returns data back through the gateway to the UI.
- Bulk import/export flows: UI → Node (uploads file) → Node processes & calls external API → returns status.

c. Architectural Patterns & Principles
- Full-stack separation (UI vs. service)
- Schema-first GraphQL API (schema.graphql + resolvers)
- Single responsibility per resolver folder (one entity-per-module)
- Reusable client wrappers for external GraphQL calls
- i18n using JSON resource bundles for static text and for data translations

d. Technologies & Frameworks
- Frontend: React, TypeScript, VTEX Styleguide components, GraphQL (Apollo or fetch), custom hooks & context
- Backend: Node.js (TypeScript), VTEX IO service.json, GraphQL resolvers
- Deployment & Hosting: VTEX IO platform
- Data: External VTEX Catalog GraphQL service

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        ReactUI["React Admin UI"]:::frontend
        subgraph "Entity Translation Screens"
            direction TB
            Brand["BrandTranslation.tsx"]:::frontend
            Cat["CategoryTranslation.tsx"]:::frontend
            Coll["CollectionsTranslation.tsx"]:::frontend
            Prod["ProductTranslation.tsx"]:::frontend
            SKU["SKUTranslation.tsx"]:::frontend
            Spec["SpecificationsTranslation.tsx"]:::frontend
        end
        SharedUI["Shared UI Components"]:::frontend
        GraphQLOps["GraphQL Queries/Mutations"]:::frontend
        Hooks["Hooks & Providers"]:::frontend
        ReactUI -->|"renders"| Brand
        ReactUI -->|"renders"| Cat
        ReactUI -->|"renders"| Coll
        ReactUI -->|"renders"| Prod
        ReactUI -->|"renders"| SKU
        ReactUI -->|"renders"| Spec
        ReactUI --> SharedUI
        ReactUI --> Hooks
        ReactUI --> GraphQLOps
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        NodeService["Node Service"]:::backend
        IndexTS["index.ts"]:::backend
        ServiceJSON["service.json"]:::backend
        subgraph Clients
            direction TB
            CatClient["catalog.ts"]:::backend
            CatGQLClient["catalogGQL.ts"]:::backend
            UtilsQueries["catalogGQLQueries.ts"]:::backend
        end
        subgraph Resolvers
            direction TB
            BRes["brand resolvers"]:::backend
            CRes["category resolvers"]:::backend
            CollRes["collection resolvers"]:::backend
            FieldRes["field resolvers"]:::backend
            ProdRes["product resolvers"]:::backend
            SKURes["sku resolvers"]:::backend
            TransRes["translation resolvers"]:::backend
        end
        UtilBackend["Shared Backend Utilities"]:::backend

        NodeService --> IndexTS
        NodeService --> ServiceJSON
        NodeService --> Clients
        NodeService --> Resolvers
        NodeService --> UtilBackend
    end

    %% External Services
    subgraph "VTEX Platform"
        direction TB
        Gateway["VTEX IO GraphQL Gateway"]:::external
        CatalogAPI["VTEX Catalog GraphQL API"]:::external
    end

    %% Static Resources
    subgraph "Static Assets & Config"
        direction TB
        AdminConfig["Admin Navigation & Routes"]:::static
        Localization["Localization Resources"]:::static
        Metadata["Static Metadata & Assets"]:::static
    end

    %% Data Flows
    Brand -->|graphql request| Gateway
    Cat -->|graphql request| Gateway
    Coll -->|graphql request| Gateway
    Prod -->|graphql request| Gateway
    SKU -->|graphql request| Gateway
    Spec -->|graphql request| Gateway
    GraphQLOps -->|uses| Gateway

    Gateway -->|resolves via| NodeService
    NodeService -->|calls| CatClient
    NodeService -->|calls| CatGQLClient
    CatGQLClient -->|queries/mutations| CatalogAPI
    CatalogAPI -->|responses| CatGQLClient
    CatGQLClient -->|returns| NodeService
    NodeService -->|responds| Gateway
    Gateway -->|returns data| ReactUI

    ReactUI <-->|loads| Localization
    ReactUI <-->|loads| Metadata
    AdminConfig --> ReactUI

    %% Click Events
    click Brand "https://github.com/vtex-apps/admin-catalog-translations/blob/main/react/BrandTranslation.tsx"
    click Cat "https://github.com/vtex-apps/admin-catalog-translations/blob/main/react/CategoryTranslation.tsx"
    click Coll "https://github.com/vtex-apps/admin-catalog-translations/blob/main/react/CollectionsTranslation.tsx"
    click Prod "https://github.com/vtex-apps/admin-catalog-translations/blob/main/react/ProductTranslation.tsx"
    click SKU "https://github.com/vtex-apps/admin-catalog-translations/blob/main/react/SKUTranslation.tsx"
    click Spec "https://github.com/vtex-apps/admin-catalog-translations/blob/main/react/SpecificationsTranslation.tsx"
    click SharedUI "https://github.com/vtex-apps/admin-catalog-translations/tree/main/react/components/"
    click GraphQLOps "https://github.com/vtex-apps/admin-catalog-translations/tree/main/react/graphql/"
    click Hooks "https://github.com/vtex-apps/admin-catalog-translations/tree/main/react/hooks/"
    click AdminConfig "https://github.com/vtex-apps/admin-catalog-translations/blob/main/admin/navigation.json"
    click AdminConfig "https://github.com/vtex-apps/admin-catalog-translations/blob/main/admin/routes.json"
    click IndexTS "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/index.ts"
    click ServiceJSON "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/service.json"
    click CatClient "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/clients/catalog.ts"
    click CatGQLClient "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/clients/catalogGQL.ts"
    click UtilsQueries "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/clients/utils/catalogGQLQueries.ts"
    click BRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/brand/index.ts"
    click BRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/brand/upload.ts"
    click CRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/category/index.ts"
    click CRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/category/upload.ts"
    click CollRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/collection/index.ts"
    click CollRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/collection/upload.ts"
    click FieldRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/field/index.ts"
    click FieldRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/field/upload.ts"
    click ProdRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/product/index.ts"
    click ProdRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/product/upload.ts"
    click SKURes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/sku/index.ts"
    click SKURes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/sku/upload.ts"
    click TransRes "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/resolvers/translation/index.ts"
    click UtilBackend "https://github.com/vtex-apps/admin-catalog-translations/blob/main/node/utils/index.ts"

    %% Styles
    classDef frontend fill:#e0f7e9,stroke:#2d9543,color:#000
    classDef backend fill:#e3f2fd,stroke:#2196f3,color:#000
    classDef external fill:#fff3e0,stroke:#fb8c00,color:#000
    classDef static fill:#f5f5f5,stroke:#9e9e9e,color:#000
```
