# Architecture

The modeler's React application follows established architectural patterns for
maintainability, testability, and performance. For the complete reference, see
`ui/docs/architecture-patterns.md`.

## Application structure

```
ui/src/
├── App.tsx                  # Root component with error boundary
├── index.js                 # Entry point, Drupal integration
├── standalone.tsx           # Entry point, standalone viewer (no Drupal)
├── components/              # React components
│   ├── Flow.tsx             # Main orchestrator
│   ├── FlowCanvas.tsx       # React Flow integration
│   ├── Toolbar.tsx          # Top action bar
│   ├── ExportDialog.tsx     # Export format selection dialog
│   ├── StartFlowFilter.tsx  # Flow visibility filter
│   ├── ComponentPanel.tsx   # Component library sidebar
│   ├── PropertyPanel.tsx    # Element configuration panel
│   ├── ReplayPanel.tsx      # Execution replay interface
│   ├── nodes/               # Custom node types
│   └── edges/               # Custom edge types
├── hooks/                   # Custom React hooks
├── store/                   # Zustand state management
├── types/                   # TypeScript interfaces
├── utils/                   # Utility functions
├── constants/               # Shared constants
└── styles/                  # CSS styles
```

## Key patterns

### Orchestrator pattern

`Flow.tsx` acts as the central orchestrator, coordinating between all panels
and managing the data flow. It:

- Initializes the model from `drupalSettings`.
- Manages modal state and confirmation dialogs.
- Wires up event handlers between panels.
- Coordinates replay/test workflows.

Individual components remain focused on rendering and user interaction.

### Drupal integration

The modeler integrates with Drupal through `drupalSettings`:

- **Model data**: JSON model loaded from `drupalSettings.modeler.modelData`.
- **Components**: Available plugins from `drupalSettings.modeler.components`.
- **API endpoints**: Save, config form, replay, test, export, and recipe URLs
  from `drupalSettings.modeler_api`.
- **Permissions**: Granular permissions from `drupalSettings.modeler_api.permissions`.
- **Dependencies**: Component dependency rules from `drupalSettings.modeler_api.dependencies`.
- **Component labels**: Model-owner-specific terminology from `drupalSettings.modeler_api.component_labels`.
- **CSRF tokens**: Fetched from Drupal's token endpoint for secure API calls.
- **Messages**: Drupal's `Drupal.Message` API is bridged into the modeler's UI.

### Standalone mode

The modeler can also run without Drupal via `standalone.tsx`. In this mode,
model data comes from a JSON file (exported via the JSON export format) and
the modeler operates in read-only mode. See
[Standalone Viewer](../features/standalone-viewer.md).

See `ui/docs/integration.md` for the complete integration reference.

### Error boundary hierarchy

The application uses a layered error boundary approach:

- **App-level boundary**: Catches fatal errors and offers retry.
- **Panel-level boundaries**: Individual panels have `PanelErrorBoundary`
  components that can auto-retry without crashing the entire application.

### CSS architecture

All styles are scoped to the `.modeler` class with `all: revert` to prevent
Drupal admin theme styles from leaking in. The modeler uses approximately 98
CSS custom properties for consistent theming:

- **Colors**: `--modeler-color-*`
- **Typography**: `--modeler-font-*`
- **Spacing**: `--modeler-radius-*`
- **Dark mode**: Overridden in `.modeler.dark-mode` blocks.

See `ui/docs/code-quality.md` for the complete CSS variable reference.
