# livewire/livewire architecture

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

- Interactive diagram: https://gitdiagram.com/livewire/livewire
- Repository: https://github.com/livewire/livewire

## Overview

#### Purpose and integration surface
Livewire is a Laravel package for server-authored, dynamically updated UI components. Laravel applications consume its PHP API/components and load its browser runtime. Primary integration and bootstrap points are `src/LivewireServiceProvider.php`, `src/Livewire.php`, and `js/index.js`.

#### Component model and discovery
A component is a PHP class with public state, actions, rendering, and lifecycle behavior. `LivewireManager` coordinates component registration and invocation; `Finder` resolves named, view-based, single-file, and multi-file components. Key paths: `src/Component.php`, `src/LivewireManager.php`, `src/Finder/Finder.php`.

#### Server request/render pipeline
Laravel routes Livewire update requests into request handling, which validates protocol/security constraints and delegates to the component mechanism. Component handling hydrates a client snapshot, applies property updates and method calls, renders Blade, dehydrates a new snapshot/effects payload, and signs/verifies payloads. Key boundaries: `src/Mechanisms/HandleRequests/HandleRequests.php`, `src/Mechanisms/HandleComponents/HandleComponents.php`, `src/Mechanisms/HandleComponents/Checksum.php`.

#### State serialization and extensibility
Snapshots cross the PHP/browser boundary through synthesizers: type-specific adapters serialize and hydrate primitives, collections, models, enums, form objects, and user-defined `Wireable` values. This is the central protocol extension seam. Key paths: `src/Mechanisms/HandleSynths/HandleSynths.php`, `src/Mechanisms/HandleComponents/Synthesizers/Synth.php`, `src/Wireable.php`.

#### Browser runtime and DOM reconciliation
The JavaScript runtime discovers Livewire roots and `wire:` directives, maintains client component state, batches/intercepts interactions, sends update messages, then morphs returned HTML into the DOM. It also exposes `$wire`, hooks, events, and Alpine interoperability. Key paths: `js/lifecycle.js`, `js/request/request.js`, `js/morph.js`.

#### Feature modules
Cross-cutting behavior is implemented as independently registered PHP feature modules, with corresponding browser support where needed. Major examples include attributes/lifecycle policy, nested components, navigation, validation, pagination, streaming, redirects, and reactive/modelable properties. Key paths: `src/Features/SupportAttributes/SupportAttributes.php`, `src/Features/SupportNestingComponents/SupportNestingComponents.php`, `src/Features/SupportNavigate/SupportNavigate.php`.

#### Compilation, Blade, and assets
Livewire extends Laravel Blade compilation for component tags, stable wire keys, morph-aware markup, and single-/multi-file component compilation. It also resolves and serves/injects the browser asset endpoint. Key paths: `src/Mechanisms/CompileLivewireTags/CompileLivewireTags.php`, `src/Compiler/Compiler.php`, `src/Mechanisms/FrontendAssets/FrontendAssets.php`.

#### Infrastructure and external boundaries
Runtime requirements are PHP/Laravel and the bundled JavaScript runtime; dependencies are managed through `composer.json` and `package.json`. Uploads use Laravel storage and can issue signed or multipart Amazon S3 upload flows; the browser runtime supports form, chunked, and S3 strategies. Key paths: `src/Features/SupportFileUploads/SupportFileUploads.php`, `src/Features/SupportFileUploads/S3MultipartUpload.php`, `js/features/supportFileUploads/strategies/s3.js`.

Main entry points: [`src/Mechanisms/HandleComponents/HandleComponents.php`](https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleComponents/HandleComponents.php) (Component handler), [`src/LivewireServiceProvider.php`](https://github.com/livewire/livewire/blob/main/src/LivewireServiceProvider.php) (Service provider), [`src/Features/SupportAttributes/SupportAttributes.php`](https://github.com/livewire/livewire/blob/main/src/Features/SupportAttributes/SupportAttributes.php) (Feature modules), [`js/index.js`](https://github.com/livewire/livewire/blob/main/js/index.js) (JS runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_laravel["Laravel / PHP runtime"]
  node_provider["Service provider<br/>bootstrap"]
  node_api["Livewire API<br/>facade API<br/>[Livewire.php]"]
  node_component["Component<br/>[Component.php]"]
  node_manager["Component manager<br/>orchestrator"]
  node_finder["Component finder<br/>discovery<br/>[Finder.php]"]
  node_request_handler["Update request handler<br/>HTTP mechanism<br/>[HandleRequests.php]"]
  node_component_handler["Component handler<br/>snapshot pipeline"]
  node_checksum["Checksum<br/>payload security<br/>[Checksum.php]"]
  node_synths["Synthesizer registry<br/>serialization seam<br/>[HandleSynths.php]"]
  node_synth["Synth contract<br/>serialization adapter<br/>[Synth.php]"]
  node_wireable["Wireable<br/>extension contract<br/>[Wireable.php]"]
  node_features["Feature modules<br/>cross-cutting features"]
  node_nesting["Nested components<br/>feature module"]
  node_navigate["Navigation<br/>feature module"]
  node_compiler["Livewire compiler<br/>Blade compilation"]
  node_assets["Frontend assets<br/>asset endpoint<br/>[FrontendAssets.php]"]
  node_uploads["File uploads<br/>upload feature"]
end

subgraph group_browser["Browser runtime"]
  node_js_runtime["JS runtime<br/>browser entrypoint<br/>[index.js]"]
  node_lifecycle["Client lifecycle<br/>client state<br/>[lifecycle.js]"]
  node_client_request["Update client<br/>request transport<br/>[request.js]"]
  node_morph["DOM morphing<br/>DOM reconciliation<br/>[morph.js]"]
  node_s3_client["S3 upload strategy<br/>browser upload strategy<br/>[s3.js]"]
end

subgraph group_external["External boundaries"]
  node_app["Laravel application<br/>host application"]
  node_storage[("Laravel storage / S3<br/>storage service")]
end

node_app -->|"boots"| node_provider
node_app -->|"uses"| node_api
node_provider -->|"registers"| node_manager
node_provider -->|"registers"| node_features
node_provider -->|"enables"| node_compiler
node_provider -->|"registers"| node_assets
node_api -->|"delegates to"| node_manager
node_manager -->|"resolves via"| node_finder
node_manager -->|"invokes"| node_component
node_app -->|"routes updates to"| node_request_handler
node_request_handler -->|"delegates updates"| node_component_handler
node_component_handler -->|"hydrates and renders"| node_component
node_component_handler -->|"serializes state via"| node_synths
node_synths -->|"uses adapters"| node_synth
node_wireable -.->|"extends protocol"| node_synths
node_component_handler -->|"signs and verifies"| node_checksum
node_features -->|"includes"| node_nesting
node_features -->|"includes"| node_navigate
node_component_handler -->|"applies policies"| node_features
node_assets -->|"serves"| node_js_runtime
node_js_runtime -->|"initializes"| node_lifecycle
node_lifecycle -->|"queues interactions"| node_client_request
node_client_request -->|"update payloads"| node_request_handler
node_component_handler -->|"HTML and effects response"| node_morph
node_js_runtime -->|"updates through"| node_morph
node_uploads -->|"issues upload flows"| node_storage
node_s3_client -->|"multipart upload"| node_storage
node_js_runtime -->|"uses for S3 uploads"| node_s3_client
node_features -->|"includes"| node_uploads

click node_provider "https://github.com/livewire/livewire/blob/main/src/LivewireServiceProvider.php"
click node_api "https://github.com/livewire/livewire/blob/main/src/Livewire.php"
click node_component "https://github.com/livewire/livewire/blob/main/src/Component.php"
click node_manager "https://github.com/livewire/livewire/blob/main/src/LivewireManager.php"
click node_finder "https://github.com/livewire/livewire/blob/main/src/Finder/Finder.php"
click node_request_handler "https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleRequests/HandleRequests.php"
click node_component_handler "https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleComponents/HandleComponents.php"
click node_checksum "https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleComponents/Checksum.php"
click node_synths "https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleSynths/HandleSynths.php"
click node_synth "https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleComponents/Synthesizers/Synth.php"
click node_wireable "https://github.com/livewire/livewire/blob/main/src/Wireable.php"
click node_features "https://github.com/livewire/livewire/blob/main/src/Features/SupportAttributes/SupportAttributes.php"
click node_nesting "https://github.com/livewire/livewire/blob/main/src/Features/SupportNestingComponents/SupportNestingComponents.php"
click node_navigate "https://github.com/livewire/livewire/blob/main/src/Features/SupportNavigate/SupportNavigate.php"
click node_compiler "https://github.com/livewire/livewire/blob/main/src/Mechanisms/CompileLivewireTags/CompileLivewireTags.php"
click node_assets "https://github.com/livewire/livewire/blob/main/src/Mechanisms/FrontendAssets/FrontendAssets.php"
click node_js_runtime "https://github.com/livewire/livewire/blob/main/js/index.js"
click node_lifecycle "https://github.com/livewire/livewire/blob/main/js/lifecycle.js"
click node_client_request "https://github.com/livewire/livewire/blob/main/js/request/request.js"
click node_morph "https://github.com/livewire/livewire/blob/main/js/morph.js"
click node_uploads "https://github.com/livewire/livewire/blob/main/src/Features/SupportFileUploads/SupportFileUploads.php"
click node_s3_client "https://github.com/livewire/livewire/blob/main/js/features/supportFileUploads/strategies/s3.js"

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_provider,node_api,node_component,node_manager,node_finder,node_request_handler,node_component_handler,node_checksum,node_synths,node_synth,node_wireable,node_features,node_nesting,node_navigate,node_compiler,node_assets,node_uploads toneBlue
class node_js_runtime,node_lifecycle,node_client_request,node_morph,node_s3_client toneAmber
class node_app,node_storage toneMint
```

## Components

### Laravel / PHP runtime

Server package bootstrap, component execution, and protocol handling.

- [Service provider](https://github.com/livewire/livewire/blob/main/src/LivewireServiceProvider.php): bootstrap · Registers Livewire services, mechanisms, features, and assets. · `src/LivewireServiceProvider.php`
- [Livewire API](https://github.com/livewire/livewire/blob/main/src/Livewire.php): facade API · Public PHP integration surface. · `src/Livewire.php`
- [Component](https://github.com/livewire/livewire/blob/main/src/Component.php): component base class · Defines public state, actions, lifecycle behavior, and rendering. · `src/Component.php`
- [Component manager](https://github.com/livewire/livewire/blob/main/src/LivewireManager.php): orchestrator · Coordinates component registration and invocation. · `src/LivewireManager.php`
- [Component finder](https://github.com/livewire/livewire/blob/main/src/Finder/Finder.php): discovery · Resolves named, view, single-file, and multi-file components. · `src/Finder/Finder.php`
- [Update request handler](https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleRequests/HandleRequests.php): HTTP mechanism · Validates update protocol and delegates component handling. · `src/Mechanisms/HandleRequests/HandleRequests.php`
- [Component handler](https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleComponents/HandleComponents.php): snapshot pipeline · Hydrates, updates, renders, and dehydrates component payloads. · `src/Mechanisms/HandleComponents/HandleComponents.php`
- [Checksum](https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleComponents/Checksum.php): payload security · Signs and verifies component snapshots. · `src/Mechanisms/HandleComponents/Checksum.php`
- [Synthesizer registry](https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleSynths/HandleSynths.php): serialization seam · Selects type-specific snapshot serializers and hydrators. · `src/Mechanisms/HandleSynths/HandleSynths.php`
- [Synth contract](https://github.com/livewire/livewire/blob/main/src/Mechanisms/HandleComponents/Synthesizers/Synth.php): serialization adapter · Base protocol adapter for typed values. · `src/Mechanisms/HandleComponents/Synthesizers/Synth.php`
- [Wireable](https://github.com/livewire/livewire/blob/main/src/Wireable.php): extension contract · Lets application values define snapshot serialization. · `src/Wireable.php`
- [Feature modules](https://github.com/livewire/livewire/blob/main/src/Features/SupportAttributes/SupportAttributes.php): cross-cutting features · Registered policies such as attributes, nesting, navigation, validation, and pagination. · `src/Features/SupportAttributes/SupportAttributes.php`
- [Nested components](https://github.com/livewire/livewire/blob/main/src/Features/SupportNestingComponents/SupportNestingComponents.php): feature module · Coordinates nested component behavior. · `src/Features/SupportNestingComponents/SupportNestingComponents.php`
- [Navigation](https://github.com/livewire/livewire/blob/main/src/Features/SupportNavigate/SupportNavigate.php): feature module · Provides Livewire navigation behavior. · `src/Features/SupportNavigate/SupportNavigate.php`
- [Livewire compiler](https://github.com/livewire/livewire/blob/main/src/Mechanisms/CompileLivewireTags/CompileLivewireTags.php): Blade compilation · Compiles Livewire tags and component forms into morph-aware markup. · `src/Mechanisms/CompileLivewireTags/CompileLivewireTags.php`
- [Frontend assets](https://github.com/livewire/livewire/blob/main/src/Mechanisms/FrontendAssets/FrontendAssets.php): asset endpoint · Resolves, serves, and injects the browser runtime. · `src/Mechanisms/FrontendAssets/FrontendAssets.php`
- [File uploads](https://github.com/livewire/livewire/blob/main/src/Features/SupportFileUploads/SupportFileUploads.php): upload feature · Supports form, chunked, and signed S3 upload flows. · `src/Features/SupportFileUploads/SupportFileUploads.php`

### Browser runtime

Client state, requests, DOM updates, and upload support.

- [JS runtime](https://github.com/livewire/livewire/blob/main/js/index.js): browser entrypoint · Initializes Livewire client behavior and integrations. · `js/index.js`
- [Client lifecycle](https://github.com/livewire/livewire/blob/main/js/lifecycle.js): client state · Discovers roots and directives and maintains client components. · `js/lifecycle.js`
- [Update client](https://github.com/livewire/livewire/blob/main/js/request/request.js): request transport · Batches interactions and sends update messages. · `js/request/request.js`
- [DOM morphing](https://github.com/livewire/livewire/blob/main/js/morph.js): DOM reconciliation · Applies returned HTML to the browser DOM. · `js/morph.js`
- [S3 upload strategy](https://github.com/livewire/livewire/blob/main/js/features/supportFileUploads/strategies/s3.js): browser upload strategy · Performs browser-side multipart S3 uploads. · `js/features/supportFileUploads/strategies/s3.js`

### External boundaries

Host application and storage services.

- **Laravel application**: host application · Consumes Livewire components and routes update requests.
- **Laravel storage / S3**: storage service · Receives stored or multipart uploaded files.

## Connections

- Laravel application → Service provider: boots
- Laravel application → Livewire API: uses
- Service provider → Component manager: registers
- Service provider → Feature modules: registers
- Service provider → Livewire compiler: enables
- Service provider → Frontend assets: registers
- Livewire API → Component manager: delegates to
- Component manager → Component finder: resolves via
- Component manager → Component: invokes
- Laravel application → Update request handler: routes updates to
- Update request handler → Component handler: delegates updates
- Component handler → Component: hydrates and renders
- Component handler → Synthesizer registry: serializes state via
- Synthesizer registry → Synth contract: uses adapters
- Wireable → Synthesizer registry: extends protocol
- Component handler → Checksum: signs and verifies
- Feature modules → Nested components: includes
- Feature modules → Navigation: includes
- Component handler → Feature modules: applies policies
- Frontend assets → JS runtime: serves
- JS runtime → Client lifecycle: initializes
- Client lifecycle → Update client: queues interactions
- Update client → Update request handler: update payloads
- Component handler → DOM morphing: HTML and effects response
- JS runtime → DOM morphing: updates through
- File uploads → Laravel storage / S3: issues upload flows
- S3 upload strategy → Laravel storage / S3: multipart upload
- JS runtime → S3 upload strategy: uses for S3 uploads
- Feature modules → File uploads: includes
