Frontend Architecture & Theming

Relevant source files

The following files were used as context for generating this wiki page:

• datahub-web-react/README.md
• datahub-web-react/CLAUDE.md
• datahub-web-react/index.html
• datahub-web-react/src/app/entityV2/document/changeHistory/ARCHITECTURE.md
• datahub-web-react/src/app/entityV2/document/summary/EditableContent.tsx
• docs-website/generateDocsDir.ts

Introduction

The DataHub frontend is a modern React application designed with two primary pillars: Configurability and Extensibility. It serves as the primary user interface for data discovery, governance, and observability, interacting with the datahub-frontend server via a GraphQL API. The architecture is built to allow organizations to tailor the client experience through theme adjustments, custom logos, and the addition of new metadata entities with minimal effort.

The system leverages Apollo Client for data management and is transitioning toward a bespoke component library powered by styled-components, moving away from legacy Ant Design dependencies. This architecture ensures that new features, such as document change history or interactive editors, follow a consistent pattern of testability and type safety.

Sources: datahub-web-react/README.md:14-22, datahub-web-react/CLAUDE.md:104-105

Core Architecture

The application is structured into functional modules that separate configuration, data fetching, and UI rendering.

Package Organization

The src directory is divided into several high-level modules:

• app: Contains the core application components including authentication, search, and entity-specific logic.
• graphql: Stores GraphQL queries and mutations. The project uses code generation (yarn generate) to produce TypeScript types from these definitions.
• conf: Houses global configuration flags, such as search result limits and placeholder text.
• shared: Contains miscellaneous shared components, hooks, and utilities.

Sources: datahub-web-react/README.md:144-180, datahub-web-react/CLAUDE.md:7-14

Data Flow and GraphQL

The frontend communicates exclusively with the backend via GraphQL. This flow involves declaring queries in .graphql files, generating TypeScript types, and using Apollo hooks within React components to fetch or mutate data.

The Entity Registry

A critical architectural component is the EntityRegistry. This abstraction layer manages how different metadata entities (e.g., Datasets, Users, Pipelines) are rendered without the core app needing intimate knowledge of each entity's structure.

Component	Responsibility
Entity Interface	Defines methods for rendering Profiles and Previews.
Profiles	Display full details of an individual entity instance.
Previews	Small cards used in search and browse results.
EntityRegistry	Centralized map used to retrieve entity-specific UI logic by EntityType.

Sources: datahub-web-react/README.md:172-180

Theming System

DataHub employs a flexible theming system that supports both environment-variable-driven customizations and deep code-level theme definitions.

Dynamic Customization (No Rebuild)

Certain visual elements can be customized without rebuilding the Docker container by setting environment variables in the GMS (Metadata Service):

• REACT_APP_LOGO_URL: Customizes the homepage and search bar logo.
• REACT_APP_FAVICON_URL: Overrides the browser tab icon.

Sources: datahub-web-react/README.md:108-115, datahub-web-react/index.html:6-7

Theme Configuration

Themes are defined in src/conf/theme/themes.ts. The active theme is determined by the REACT_APP_CUSTOM_THEME_ID env variable. If none is provided, the system defaults to themeV2 or themeV1 based on UI configuration.

A theme object consists of four main sections:

1. colors: Semantic color tokens (the primary configuration method going forward).
2. styles: Overrides for deprecated variables and Ant Design components.
3. assets: Configuration for asset URLs (like logos).
4. content: Customizable text fields within the UI.

Sources: datahub-web-react/README.md:117-139, datahub-web-react/src/app/entityV2/document/summary/EditableContent.tsx:28-40

Implementation with Styled Components

The project uses styled-components for styling, following a pattern of passing a theme object through a provider.

Component Design Patterns

DataHub enforces strict guidelines to ensure UI components are reusable and maintainable.

Component Categorization

• DataHub Components: Generalized, reusable UI elements that do not depend on GMS aspects or GraphQL types.
• Shared Entity Components: Reusable within DataHub but may depend on GMS-specific data structures (e.g., EntityHealth, HoverEntityTooltip).
• Entity Components: Implementation-specific views located within src/app/entity/.

Sources: datahub-web-react/CLAUDE.md:31-50

Best Practices for Logic Extraction

To maintain testability, complex logic is extracted from JSX into:

1. Pure Utility Functions: For data transformation (e.g., extractChangeDetails).
2. Custom Hooks: For side effects and data fetching (e.g., useParentDocumentTitle).

Development Workflow

The frontend development lifecycle includes automated type generation and strict linting to maintain code quality.

Key Commands

Command	Purpose
yarn generate	Generates TypeScript types from GraphQL definitions.
yarn start	Launches the local development server on localhost:3000.
yarn test	Executes unit tests using Vitest and React Testing Library.
yarn lint	Runs ruff and prettier to enforce style consistency.

Sources: datahub-web-react/README.md:65-72, datahub-web-react/CLAUDE.md:120-143

Conclusion

The Frontend Architecture of DataHub is a decoupled, registry-based system that prioritizes developer agility and organizational branding. By utilizing an Entity Registry and a semantic theming system, the platform allows for rapid extension of metadata models while maintaining a cohesive user experience. The transition toward centralized "DataHub Components" and pure utility logic ensures the codebase remains robust as the project scales.