# rrousselgit/riverpod architecture

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

- Interactive diagram: https://gitdiagram.com/rrousselgit/riverpod
- Repository: https://github.com/rrousselgit/riverpod

## Overview

1. **This is a monorepo for the Riverpod ecosystem**
   The repository is centered on the `riverpod` state-management framework and related packages. It is not a single app: it contains runtime libraries, Flutter integrations, code generators, lints, a devtool, persistence helpers, a documentation website, benchmarks, and many example apps.

2. **The core runtime lives in `packages/riverpod`**
   This is the main engine. Its architectural center is the provider system: `ProviderContainer`, `ProviderScope`, `Ref`, provider elements/subscriptions, and the `AsyncValue` model for async state. Providers are the unit of state/logic, and the container is the boundary that stores, resolves, overrides, and disposes them.

3. **`packages/flutter_riverpod` and `packages/hooks_riverpod` adapt the core to Flutter**
   These packages are thin presentation-layer bridges over the core runtime. They provide Flutter-facing consumer widgets and widget references so UI can read/watch providers without directly managing lifecycle plumbing. The boundaries here are: Flutter widget tree on one side, Riverpod container/ref APIs on the other.

4. **Generated providers are a first-class part of the architecture**
   The repo heavily supports code generation. `packages/riverpod_annotation` defines annotations such as `@riverpod`, while `packages/riverpod_generator` parses annotated Dart source and emits `*.g.dart` provider glue. Generated code appears throughout examples and docs, showing that handwritten logic is often transformed into provider declarations automatically.

5. **Static analysis and developer feedback are handled separately from runtime**
   `packages/riverpod_analyzer_utils`, `packages/riverpod_lint`, `packages/internal_lint`, and `packages/lint_visitor_generator` form the analysis/linting layer. These packages inspect Dart ASTs, infer provider usage, detect Riverpod-specific mistakes, and offer fixes/assists. This layer enforces architectural rules such as provider dependency correctness, scoping, and safe notifier usage.

6. **The devtool is a separate introspection subsystem**
   `packages/riverpod_devtool` is a Flutter web app that connects to the Dart VM service. It inspects live provider state, frames, and object graphs, and includes search/filtering utilities. This is the runtime observability boundary: the app does not manage state itself, it queries a running app for Riverpod internals and renders them in a UI.

7. **Persistence and offline support are modeled as extensions**
   `packages/riverpod_sqflite` and the experimental persistence APIs in `riverpod`/`flutter_riverpod` add storage-backed state. The architecture here is provider state flowing through a persistence adapter into local storage, enabling offline restore and cached state behavior without changing the app’s provider model.

8. **Examples demonstrate the intended app architecture**
   The `examples/` folder contains multiple small applications (`counter`, `todos`, `pub`, `marvel`, `stackoverflow`, `random_number`, `first_app`). These show the standard flow: domain/data layer feeds providers, providers expose async or synchronous state, and UI widgets consume that state. Many examples include generated files, reinforcing the codegen-based architecture.

9. **The documentation website is itself a content application**
   `website/` is a Docusaurus site with React/TypeScript UI components plus embedded Dart example code. It is not just static markdown: it has custom components, snippet generation, localization, and many runnable example fragments. The docs system is part educational content, part executable reference implementation.

10. **Benchmarks and tooling are isolated from the product runtime**
   `benchmarks/` measures provider operations such as creation, reads, listener add/remove. `scripts/` and `tools/` provide repo-wide automation and generation utilities. These are supporting subsystems, not part of the app runtime, but they validate performance and keep generated artifacts consistent.

11. **Tests are broad and stratified by layer**
   Each package has its own tests, and the repo includes integration fixtures with generated outputs. The runtime packages test provider mechanics and lifecycle behavior, generator packages test emitted code, lint packages test diagnostics and fixes, and devtool/tests validate VM-service-driven inspection. This shows a layered architecture with strong contract testing between core, generator, analyzer, and UI-facing packages.

12. **Main data flow across the repo**
   In the common Riverpod flow, user code declares providers or annotations, the generator/lints analyze and enrich that code, the runtime container executes providers and caches results, Flutter consumers read state and rebuild UI, and optional tooling such as the devtool or persistence layers observe or store the same provider state. The repository’s architecture is built around those boundaries rather than around a single application server/client split.

Main entry points: [`packages/riverpod/lib/riverpod.dart`](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/riverpod.dart) (Riverpod core), [`packages/riverpod_generator/lib/src/riverpod_generator.dart`](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_generator/lib/src/riverpod_generator.dart) (Generator), [`website/src/pages/index.tsx`](https://github.com/rrousselgit/riverpod/blob/master/website/src/pages/index.tsx) (Website), [`packages/flutter_riverpod/lib/flutter_riverpod.dart`](https://github.com/rrousselgit/riverpod/blob/master/packages/flutter_riverpod/lib/flutter_riverpod.dart) (Flutter Riverpod)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_riverpod_core["Riverpod core<br/>runtime library<br/>[riverpod.dart]"]
  node_provider_container["Container<br/>state boundary"]
  node_provider_system["Providers<br/>provider model<br/>[provider.dart]"]
  node_ref_api["Ref API<br/>read/write API<br/>[ref.dart]"]
  node_async_value["AsyncValue<br/>state model<br/>[async_value.dart]"]
end

subgraph group_flutter["Flutter adapters"]
  node_flutter_riverpod["Flutter Riverpod<br/>flutter bridge"]
  node_consumer_widget["Consumer UI<br/>widget bridge<br/>[consumer.dart]"]
  node_provider_scope["ProviderScope<br/>scope widget"]
  node_hooks_riverpod["Hooks Riverpod<br/>flutter bridge"]
end

subgraph group_generation["Generation"]
  node_riverpod_annotation["Annotations"]
  node_riverpod_generator["Generator"]
  node_generator_templates["Templates<br/>[template.dart]"]
end

subgraph group_analysis["Analysis"]
  node_analyzer_utils["Analyzer utils<br/>analysis helpers"]
  node_riverpod_lint["Riverpod lint<br/>custom lint<br/>[main.dart]"]
  node_internal_lint["Internal lint<br/>lint rules<br/>[main.dart]"]
end

subgraph group_tooling["Tooling"]
  node_devtool["Devtool<br/>flutter web app<br/>[main.dart]"]
  node_sqflite_persist["Sqflite persist<br/>persistence adapter"]
  node_benchmarks["Benchmarks<br/>performance suite<br/>[main.dart]"]
end

subgraph group_content["Content apps"]
  node_examples["Examples<br/>sample apps<br/>[main.dart]"]
  node_website["Website<br/>docs site<br/>[index.tsx]"]
end

node_riverpod_core -->|"contains"| node_provider_container
node_riverpod_core -->|"implements"| node_provider_system
node_riverpod_core -->|"exposes"| node_ref_api
node_riverpod_core -->|"models"| node_async_value
node_provider_container -->|"manages"| node_provider_system
node_provider_system -->|"uses"| node_ref_api
node_flutter_riverpod -->|"provides"| node_consumer_widget
node_flutter_riverpod -->|"provides"| node_provider_scope
node_consumer_widget -->|"reads"| node_riverpod_core
node_provider_scope -->|"hosts"| node_provider_container
node_hooks_riverpod -->|"adapts"| node_riverpod_core
node_riverpod_annotation -->|"drives"| node_riverpod_generator
node_riverpod_generator -->|"renders"| node_generator_templates
node_riverpod_generator -->|"targets"| node_riverpod_core
node_analyzer_utils -->|"supports"| node_riverpod_lint
node_riverpod_lint -.->|"aligns with"| node_riverpod_generator
node_internal_lint -.->|"complements"| node_riverpod_lint
node_devtool -->|"inspects"| node_riverpod_core
node_sqflite_persist -->|"extends"| node_riverpod_core
node_benchmarks -.->|"measures"| node_riverpod_core
node_examples -->|"uses"| node_riverpod_core
node_examples -.->|"shows"| node_riverpod_generator
node_website -->|"documents"| node_riverpod_core
node_website -->|"documents"| node_flutter_riverpod
node_website -->|"documents"| node_riverpod_generator

click node_riverpod_core "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/riverpod.dart"
click node_provider_container "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/src/core/provider_container.dart"
click node_provider_system "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/src/core/provider/provider.dart"
click node_ref_api "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/src/core/ref.dart"
click node_async_value "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/src/core/async_value.dart"
click node_flutter_riverpod "https://github.com/rrousselgit/riverpod/blob/master/packages/flutter_riverpod/lib/flutter_riverpod.dart"
click node_consumer_widget "https://github.com/rrousselgit/riverpod/blob/master/packages/flutter_riverpod/lib/src/core/consumer.dart"
click node_provider_scope "https://github.com/rrousselgit/riverpod/blob/master/packages/flutter_riverpod/lib/src/core/provider_scope.dart"
click node_hooks_riverpod "https://github.com/rrousselgit/riverpod/blob/master/packages/hooks_riverpod/lib/hooks_riverpod.dart"
click node_riverpod_annotation "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_annotation/lib/riverpod_annotation.dart"
click node_riverpod_generator "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_generator/lib/src/riverpod_generator.dart"
click node_generator_templates "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_generator/lib/src/templates/template.dart"
click node_analyzer_utils "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_analyzer_utils/lib/riverpod_analyzer_utils.dart"
click node_riverpod_lint "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_lint/lib/main.dart"
click node_internal_lint "https://github.com/rrousselgit/riverpod/blob/master/packages/internal_lint/lib/main.dart"
click node_devtool "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_devtool/lib/main.dart"
click node_sqflite_persist "https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_sqflite/lib/riverpod_sqflite.dart"
click node_benchmarks "https://github.com/rrousselgit/riverpod/blob/master/benchmarks/lib/main.dart"
click node_examples "https://github.com/rrousselgit/riverpod/blob/master/examples/counter/lib/main.dart"
click node_website "https://github.com/rrousselgit/riverpod/blob/master/website/src/pages/index.tsx"

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_riverpod_core,node_provider_container,node_provider_system,node_ref_api,node_async_value toneBlue
class node_flutter_riverpod,node_consumer_widget,node_provider_scope,node_hooks_riverpod toneAmber
class node_riverpod_annotation,node_riverpod_generator,node_generator_templates toneMint
class node_analyzer_utils,node_riverpod_lint,node_internal_lint toneRose
class node_devtool,node_sqflite_persist,node_benchmarks toneIndigo
class node_examples,node_website toneTeal
```

## Components

### Core runtime

Provider engine, state model, and runtime extensions.

- [Riverpod core](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/riverpod.dart): runtime library · Main provider container, ref, provider, and AsyncValue runtime. · `packages/riverpod/lib/riverpod.dart`
- [Container](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/src/core/provider_container.dart): state boundary · Creates, resolves, overrides, and disposes provider state. · `packages/riverpod/lib/src/core/provider_container.dart`
- [Providers](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/src/core/provider/provider.dart): provider model · Functional, notifier, async, stream, and family provider implementations. · `packages/riverpod/lib/src/core/provider/provider.dart`
- [Ref API](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/src/core/ref.dart): read/write API · Provider-side access to dependencies, lifecycle, and mutations. · `packages/riverpod/lib/src/core/ref.dart`
- [AsyncValue](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod/lib/src/core/async_value.dart): state model · Represents loading, data, and error states for async providers. · `packages/riverpod/lib/src/core/async_value.dart`

### Flutter adapters

Widget-facing Riverpod integrations.

- [Flutter Riverpod](https://github.com/rrousselgit/riverpod/blob/master/packages/flutter_riverpod/lib/flutter_riverpod.dart): flutter bridge · Flutter widget integration over the core runtime. · `packages/flutter_riverpod/lib/flutter_riverpod.dart`
- [Consumer UI](https://github.com/rrousselgit/riverpod/blob/master/packages/flutter_riverpod/lib/src/core/consumer.dart): widget bridge · Consumer widgets and widget refs for reading providers in Flutter. · `packages/flutter_riverpod/lib/src/core/consumer.dart`
- [ProviderScope](https://github.com/rrousselgit/riverpod/blob/master/packages/flutter_riverpod/lib/src/core/provider_scope.dart): scope widget · Widget-tree boundary that injects and overrides provider containers. · `packages/flutter_riverpod/lib/src/core/provider_scope.dart`
- [Hooks Riverpod](https://github.com/rrousselgit/riverpod/blob/master/packages/hooks_riverpod/lib/hooks_riverpod.dart): flutter bridge · Flutter hooks integration layered on top of the core runtime. · `packages/hooks_riverpod/lib/hooks_riverpod.dart`

### Generation

Annotations and source generation for providers.

- [Annotations](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_annotation/lib/riverpod_annotation.dart): source annotations · Defines @riverpod and related opt-in annotations for code generation. · `packages/riverpod_annotation/lib/riverpod_annotation.dart`
- [Generator](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_generator/lib/src/riverpod_generator.dart): code generator · Parses annotated Dart and emits provider glue and generated files. · `packages/riverpod_generator/lib/src/riverpod_generator.dart`
- [Templates](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_generator/lib/src/templates/template.dart): generation templates · Reusable snippets for providers, notifiers, families, and hashes. · `packages/riverpod_generator/lib/src/templates/template.dart`

### Analysis

Static analysis, lints, and assist infrastructure.

- [Analyzer utils](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_analyzer_utils/lib/riverpod_analyzer_utils.dart): analysis helpers · AST and type utilities for Riverpod-specific static analysis. · `packages/riverpod_analyzer_utils/lib/riverpod_analyzer_utils.dart`
- [Riverpod lint](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_lint/lib/main.dart): custom lint · Diagnostics, fixes, and assists for Riverpod usage patterns. · `packages/riverpod_lint/lib/main.dart`
- [Internal lint](https://github.com/rrousselgit/riverpod/blob/master/packages/internal_lint/lib/main.dart): lint rules · Repository-specific lint rules and visitors. · `packages/internal_lint/lib/main.dart`

### Tooling

Devtool, persistence, benchmarks, and repo automation.

- [Devtool](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_devtool/lib/main.dart): flutter web app · Live provider inspection UI backed by VM service data. · `packages/riverpod_devtool/lib/main.dart`
- [Sqflite persist](https://github.com/rrousselgit/riverpod/blob/master/packages/riverpod_sqflite/lib/riverpod_sqflite.dart): persistence adapter · Local storage persistence for provider state and offline restore. · `packages/riverpod_sqflite/lib/riverpod_sqflite.dart`
- [Benchmarks](https://github.com/rrousselgit/riverpod/blob/master/benchmarks/lib/main.dart): performance suite · Measures provider creation, reads, and listener operations. · `benchmarks/lib/main.dart`

### Content apps

Examples and documentation site built around Riverpod.

- [Examples](https://github.com/rrousselgit/riverpod/blob/master/examples/counter/lib/main.dart): sample apps · Counter, todos, pub, marvel, stackoverflow, and other sample applications. · `examples/counter/lib/main.dart`
- [Website](https://github.com/rrousselgit/riverpod/blob/master/website/src/pages/index.tsx): docs site · Docusaurus documentation site with embedded runnable Riverpod examples. · `website/src/pages/index.tsx`

## Connections

- Riverpod core → Container: contains · Core runtime centers on the container boundary.
- Riverpod core → Providers: implements · Provider types are the primary runtime abstraction.
- Riverpod core → Ref API: exposes · Provider logic runs through Ref.
- Riverpod core → AsyncValue: models · Async state is represented through AsyncValue.
- Container → Providers: manages · Container stores and disposes provider instances.
- Providers → Ref API: uses · Providers interact with dependencies and lifecycle through Ref.
- Flutter Riverpod → Consumer UI: provides · Flutter-facing consumer widgets wrap the core APIs.
- Flutter Riverpod → ProviderScope: provides · ProviderScope creates widget-tree container boundaries.
- Consumer UI → Riverpod core: reads · Widgets watch provider state from the core runtime.
- ProviderScope → Container: hosts · Scopes inject a ProviderContainer into Flutter trees.
- Hooks Riverpod → Riverpod core: adapts · Hooks integration builds on the same core engine.
- Annotations → Generator: drives · Annotations are input to generated provider glue.
- Generator → Templates: renders · Generator emits provider and notifier templates.
- Generator → Riverpod core: targets · Generated code instantiates core provider types.
- Analyzer utils → Riverpod lint: supports · Shared analysis helpers power lint diagnostics.
- Riverpod lint → Generator: aligns with · Lint rules reflect the generated-provider architecture.
- Internal lint → Riverpod lint: complements · Internal linting adds repository-specific rules.
- Devtool → Riverpod core: inspects · The devtool reads live Riverpod provider state.
- Sqflite persist → Riverpod core: extends · Persistence adapter stores provider state offline.
- Benchmarks → Riverpod core: measures · Benchmarks evaluate provider runtime operations.
- Examples → Riverpod core: uses · Sample apps demonstrate the core provider flow.
- Examples → Generator: shows · Examples commonly include generated provider glue.
- Website → Riverpod core: documents · Docs explain core concepts and provider behavior.
- Website → Flutter Riverpod: documents · Documentation includes Flutter consumer patterns.
- Website → Generator: documents · Docs include codegen-oriented examples.
