# availity/element architecture

> Architecture diagram of the GitHub repository availity/element, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/availity/element
- Repository: https://github.com/availity/element

## Overview

Availity Element is a reusable React component library for the Availity design system, built on Material UI and design tokens. A consuming application wraps its UI in the theme provider and imports components from the aggregate Element package. Beyond general UI primitives, the workspace provides controlled forms, authorization, favorites, and Spaces navigation with SSO and payer/disclaimer modal flows. The graph emphasizes those distinct product areas; several package implementations are represented by their exact source paths, but their internal calls were not sampled.

Main entry points: [`packages/spaces/src/lib/SpacesLink/linkHandlers.tsx`](https://github.com/availity/element/blob/main/packages/spaces/src/lib/SpacesLink/linkHandlers.tsx) (Link handlers), [`packages/spaces/src/lib/SpacesLink/useLink.tsx`](https://github.com/availity/element/blob/main/packages/spaces/src/lib/SpacesLink/useLink.tsx) (Space link hook), [`packages/spaces/src/lib/modals/ModalProvider.tsx`](https://github.com/availity/element/blob/main/packages/spaces/src/lib/modals/ModalProvider.tsx) (Modal provider), [`packages/favorites/src/lib/utils.ts`](https://github.com/availity/element/blob/main/packages/favorites/src/lib/utils.ts) (Favorites operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_themeprovider["Theme provider<br/>[theme-provider.tsx]"]
  node_element["Component exports<br/>[index.ts]"]
end

subgraph group_ui["UI foundation"]
  node_design_tokens["Design tokens<br/>[index.ts]"]
  node_theme["Legacy theme<br/>[legacy-theme.ts]"]
end

subgraph group_forms["Forms and access"]
  node_autocomplete["Autocomplete<br/>[Autocomplete.tsx]"]
  node_controlled_form["Controlled form<br/>[Autocomplete.tsx]"]
  node_form_utils["Form utilities<br/>[SearchBy.tsx]"]
  node_authorization["Authorization gate<br/>[Authorize.tsx]"]
end

subgraph group_spaces["Spaces navigation"]
  node_spaces["Spaces provider<br/>[Spaces.tsx]"]
  node_space_link["Space link hook<br/>[useLink.tsx]"]
  node_link_handlers["Link handlers<br/>[linkHandlers.tsx]"]
  node_modal_provider["Modal provider<br/>[ModalProvider.tsx]"]
  node_spaces_helpers["URL helpers<br/>[helpers.tsx]"]
  node_top_apps["Top apps<br/>[topApps.tsx]"]
end

subgraph group_state["User state"]
  node_favorites["Favorites<br/>[Favorites.tsx]"]
  node_favorites_helpers["Favorites operations<br/>[utils.ts]"]
end

node_consumer(("Consuming app"))
node_native_form["Native form service"]
node_favorite_service["Favorites service"]

node_consumer -->|"wraps UI"| node_themeprovider
node_consumer -->|"imports components"| node_element
node_theme -->|"styles with"| node_design_tokens
node_spaces -->|"provides spaces"| node_space_link
node_space_link -->|"opens modal"| node_modal_provider
node_space_link -->|"dispatches link"| node_link_handlers
node_link_handlers -->|"builds URL"| node_spaces_helpers
node_link_handlers -->|"updates app"| node_top_apps
node_link_handlers -->|"submits SSO"| node_native_form
node_modal_provider -->|"builds URL"| node_spaces_helpers
node_modal_provider -->|"updates app"| node_top_apps
node_favorites -->|"loads and submits"| node_favorites_helpers
node_favorites_helpers -.->|"queries service"| node_favorite_service

click node_themeprovider "https://github.com/availity/element/blob/main/packages/theme-provider/src/lib/theme-provider.tsx"
click node_element "https://github.com/availity/element/blob/main/packages/element/src/index.ts"
click node_design_tokens "https://github.com/availity/element/blob/main/packages/design-tokens/src/index.ts"
click node_theme "https://github.com/availity/element/blob/main/packages/theme/src/lib/legacy-theme.ts"
click node_autocomplete "https://github.com/availity/element/blob/main/packages/autocomplete/src/lib/Autocomplete.tsx"
click node_controlled_form "https://github.com/availity/element/blob/main/packages/controlled-form/src/lib/Autocomplete.tsx"
click node_form_utils "https://github.com/availity/element/blob/main/packages/form-utils/src/lib/SearchBy.tsx"
click node_authorization "https://github.com/availity/element/blob/main/packages/authorize/src/lib/Authorize.tsx"
click node_spaces "https://github.com/availity/element/blob/main/packages/spaces/src/lib/Spaces.tsx"
click node_space_link "https://github.com/availity/element/blob/main/packages/spaces/src/lib/SpacesLink/useLink.tsx"
click node_link_handlers "https://github.com/availity/element/blob/main/packages/spaces/src/lib/SpacesLink/linkHandlers.tsx"
click node_modal_provider "https://github.com/availity/element/blob/main/packages/spaces/src/lib/modals/ModalProvider.tsx"
click node_spaces_helpers "https://github.com/availity/element/blob/main/packages/spaces/src/lib/helpers.tsx"
click node_top_apps "https://github.com/availity/element/blob/main/packages/spaces/src/lib/topApps.tsx"
click node_favorites "https://github.com/availity/element/blob/main/packages/favorites/src/lib/Favorites.tsx"
click node_favorites_helpers "https://github.com/availity/element/blob/main/packages/favorites/src/lib/utils.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_themeprovider,node_element toneBlue
class node_design_tokens,node_theme toneAmber
class node_autocomplete,node_controlled_form,node_form_utils,node_authorization toneMint
class node_spaces,node_space_link,node_link_handlers,node_modal_provider,node_spaces_helpers,node_top_apps toneRose
class node_favorites,node_favorites_helpers,node_consumer,node_native_form,node_favorite_service toneIndigo
```

## Components

### Application entry

- [Theme provider](https://github.com/availity/element/blob/main/packages/theme-provider/src/lib/theme-provider.tsx): `packages/theme-provider/src/lib/theme-provider.tsx`
- [Component exports](https://github.com/availity/element/blob/main/packages/element/src/index.ts): `packages/element/src/index.ts`

### UI foundation

- [Design tokens](https://github.com/availity/element/blob/main/packages/design-tokens/src/index.ts): `packages/design-tokens/src/index.ts`
- [Legacy theme](https://github.com/availity/element/blob/main/packages/theme/src/lib/legacy-theme.ts): `packages/theme/src/lib/legacy-theme.ts`

### Forms and access

- [Autocomplete](https://github.com/availity/element/blob/main/packages/autocomplete/src/lib/Autocomplete.tsx): `packages/autocomplete/src/lib/Autocomplete.tsx`
- [Controlled form](https://github.com/availity/element/blob/main/packages/controlled-form/src/lib/Autocomplete.tsx): `packages/controlled-form/src/lib/Autocomplete.tsx`
- [Form utilities](https://github.com/availity/element/blob/main/packages/form-utils/src/lib/SearchBy.tsx): `packages/form-utils/src/lib/SearchBy.tsx`
- [Authorization gate](https://github.com/availity/element/blob/main/packages/authorize/src/lib/Authorize.tsx): `packages/authorize/src/lib/Authorize.tsx`

### Spaces navigation

- [Spaces provider](https://github.com/availity/element/blob/main/packages/spaces/src/lib/Spaces.tsx): `packages/spaces/src/lib/Spaces.tsx`
- [Space link hook](https://github.com/availity/element/blob/main/packages/spaces/src/lib/SpacesLink/useLink.tsx): `packages/spaces/src/lib/SpacesLink/useLink.tsx`
- [Link handlers](https://github.com/availity/element/blob/main/packages/spaces/src/lib/SpacesLink/linkHandlers.tsx): `packages/spaces/src/lib/SpacesLink/linkHandlers.tsx`
- [Modal provider](https://github.com/availity/element/blob/main/packages/spaces/src/lib/modals/ModalProvider.tsx): `packages/spaces/src/lib/modals/ModalProvider.tsx`
- [URL helpers](https://github.com/availity/element/blob/main/packages/spaces/src/lib/helpers.tsx): `packages/spaces/src/lib/helpers.tsx`
- [Top apps](https://github.com/availity/element/blob/main/packages/spaces/src/lib/topApps.tsx): `packages/spaces/src/lib/topApps.tsx`

### User state

- [Favorites](https://github.com/availity/element/blob/main/packages/favorites/src/lib/Favorites.tsx): `packages/favorites/src/lib/Favorites.tsx`
- [Favorites operations](https://github.com/availity/element/blob/main/packages/favorites/src/lib/utils.ts): `packages/favorites/src/lib/utils.ts`

### Other components

- **Consuming app**
- **Native form service**
- **Favorites service**

## Connections

- Consuming app → Theme provider: wraps UI
- Consuming app → Component exports: imports components
- Legacy theme → Design tokens: styles with (evidence: `packages/theme/src/lib/legacy-theme.ts`)
- Spaces provider → Space link hook: provides spaces (evidence: `packages/spaces/src/lib/SpacesLink/useLink.tsx`)
- Space link hook → Modal provider: opens modal (evidence: `packages/spaces/src/lib/SpacesLink/useLink.tsx`)
- Space link hook → Link handlers: dispatches link (evidence: `packages/spaces/src/lib/SpacesLink/useLink.tsx`)
- Link handlers → URL helpers: builds URL (evidence: `packages/spaces/src/lib/SpacesLink/linkHandlers.tsx`)
- Link handlers → Top apps: updates app (evidence: `packages/spaces/src/lib/SpacesLink/linkHandlers.tsx`)
- Link handlers → Native form service: submits SSO (evidence: `packages/spaces/src/lib/SpacesLink/linkHandlers.tsx`)
- Modal provider → URL helpers: builds URL (evidence: `packages/spaces/src/lib/modals/ModalProvider.tsx`)
- Modal provider → Top apps: updates app (evidence: `packages/spaces/src/lib/modals/ModalProvider.tsx`)
- Favorites → Favorites operations: loads and submits (evidence: `packages/favorites/src/lib/Favorites.tsx`)
- Favorites operations → Favorites service: queries service
