# reflex-dev/reflex architecture

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

- Interactive diagram: https://gitdiagram.com/reflex-dev/reflex
- Repository: https://github.com/reflex-dev/reflex

## Overview

Reflex is a Python full-stack web framework: developers define UI components and state/event handlers, then run an app that serves the frontend and handles interactions. The README establishes that workflow; sampled source shows the app’s server role, component and state implementations, compiler, and client-state support. Unsampled areas such as plugin behavior and detailed runtime dispatch are represented conservatively; dashed edges mark relationships not verified in the excerpts.

Main entry points: [`reflex/app.py`](https://github.com/reflex-dev/reflex/blob/main/reflex/app.py) (App Definition), [`packages/reflex-base/src/reflex_base/components/component.py`](https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/components/component.py) (UI Components), [`reflex/state.py`](https://github.com/reflex-dev/reflex/blob/main/reflex/state.py) (State Model), [`packages/reflex-base/src/reflex_base/event/processor/event_processor.py`](https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/event/processor/event_processor.py) (Event Processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Python Authoring"]
  node_app_definition["App Definition<br/>[app.py]"]
  node_ui_components["UI Components<br/>[component.py]"]
  node_state_model["State Model<br/>[state.py]"]
  node_client_state["Client State<br/>[client_state.py]"]
end

subgraph group_runtime["App Runtime"]
  node_app_server["App Server<br/>[app.py]"]
  node_event_processing["Event Processing<br/>[event_processor.py]"]
  node_state_storage[("State Storage<br/>[storage.py]")]
  node_redis_manager["Redis State Manager<br/>[redis.py]"]
end

subgraph group_frontend["Frontend Generation"]
  node_compiler["Frontend Compiler<br/>[compiler.py]"]
  node_generated_frontend["Generated Frontend"]
  node_component_library["Component Library<br/>[element.py]"]
end

subgraph group_platform["Configuration and Extensions"]
  node_base_config["App Configuration<br/>[config.py]"]
  node_plugin_system["Plugin System<br/>[base.py]"]
end

node_developer(("App Developer"))
node_web_user(("Web User"))

node_developer -->|"defines app"| node_app_definition
node_developer -->|"defines UI"| node_ui_components
node_developer -->|"defines state"| node_state_model
node_app_definition -->|"runs server"| node_app_server
node_app_definition -.->|"compiles app"| node_compiler
node_ui_components -.->|"compiled by"| node_compiler
node_state_model -.->|"handles events"| node_event_processing
node_web_user -->|"uses app"| node_generated_frontend
node_generated_frontend -.->|"sends events"| node_app_server
node_app_server -.->|"dispatches events"| node_event_processing
node_event_processing -.->|"updates state"| node_state_model
node_app_server -.->|"persists state"| node_state_storage
node_redis_manager -.->|"uses storage"| node_state_storage
node_client_state -->|"provides context"| node_ui_components
node_app_definition -->|"reads config"| node_base_config
node_app_definition -->|"registers routes"| node_plugin_system
node_ui_components -.->|"uses elements"| node_component_library

click node_app_definition "https://github.com/reflex-dev/reflex/blob/main/reflex/app.py"
click node_ui_components "https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/components/component.py"
click node_state_model "https://github.com/reflex-dev/reflex/blob/main/reflex/state.py"
click node_client_state "https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/client_state.py"
click node_app_server "https://github.com/reflex-dev/reflex/blob/main/reflex/app.py"
click node_event_processing "https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/event/processor/event_processor.py"
click node_state_storage "https://github.com/reflex-dev/reflex/blob/main/reflex/istate/storage.py"
click node_redis_manager "https://github.com/reflex-dev/reflex/blob/main/reflex/istate/manager/redis.py"
click node_compiler "https://github.com/reflex-dev/reflex/blob/main/reflex/compiler/compiler.py"
click node_base_config "https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/config.py"
click node_plugin_system "https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/plugins/base.py"
click node_component_library "https://github.com/reflex-dev/reflex/blob/main/packages/reflex-components-core/src/reflex_components_core/el/element.py"

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_app_definition,node_ui_components,node_state_model,node_client_state,node_web_user toneBlue
class node_app_server,node_event_processing,node_state_storage,node_redis_manager toneAmber
class node_compiler,node_generated_frontend,node_component_library toneMint
class node_base_config,node_plugin_system toneRose
class node_developer toneIndigo
```

## Components

### Python Authoring

- [App Definition](https://github.com/reflex-dev/reflex/blob/main/reflex/app.py): `reflex/app.py`
- [UI Components](https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/components/component.py): `packages/reflex-base/src/reflex_base/components/component.py`
- [State Model](https://github.com/reflex-dev/reflex/blob/main/reflex/state.py): `reflex/state.py`
- [Client State](https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/client_state.py): `packages/reflex-base/src/reflex_base/client_state.py`

### App Runtime

- [App Server](https://github.com/reflex-dev/reflex/blob/main/reflex/app.py): `reflex/app.py`
- [Event Processing](https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/event/processor/event_processor.py): `packages/reflex-base/src/reflex_base/event/processor/event_processor.py`
- [State Storage](https://github.com/reflex-dev/reflex/blob/main/reflex/istate/storage.py): `reflex/istate/storage.py`
- [Redis State Manager](https://github.com/reflex-dev/reflex/blob/main/reflex/istate/manager/redis.py): `reflex/istate/manager/redis.py`

### Frontend Generation

- [Frontend Compiler](https://github.com/reflex-dev/reflex/blob/main/reflex/compiler/compiler.py): `reflex/compiler/compiler.py`
- **Generated Frontend**
- [Component Library](https://github.com/reflex-dev/reflex/blob/main/packages/reflex-components-core/src/reflex_components_core/el/element.py): `packages/reflex-components-core/src/reflex_components_core/el/element.py`

### Configuration and Extensions

- [App Configuration](https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/config.py): `packages/reflex-base/src/reflex_base/config.py`
- [Plugin System](https://github.com/reflex-dev/reflex/blob/main/packages/reflex-base/src/reflex_base/plugins/base.py): `packages/reflex-base/src/reflex_base/plugins/base.py`

### Other components

- **App Developer**
- **Web User**

## Connections

- App Developer → App Definition: defines app (evidence: `README.md`)
- App Developer → UI Components: defines UI (evidence: `README.md`)
- App Developer → State Model: defines state (evidence: `README.md`)
- App Definition → App Server: runs server (evidence: `README.md`)
- App Definition → Frontend Compiler: compiles app (evidence: `reflex/app.py`)
- UI Components → Frontend Compiler: compiled by (evidence: `packages/reflex-base/src/reflex_base/components/component.py`)
- State Model → Event Processing: handles events
- Web User → Generated Frontend: uses app (evidence: `README.md`)
- Generated Frontend → App Server: sends events
- App Server → Event Processing: dispatches events
- Event Processing → State Model: updates state
- App Server → State Storage: persists state
- Redis State Manager → State Storage: uses storage
- Client State → UI Components: provides context
- App Definition → App Configuration: reads config (evidence: `reflex/app.py`)
- App Definition → Plugin System: registers routes (evidence: `reflex/app.py`)
- UI Components → Component Library: uses elements
