# remix-run/remix architecture

> Architecture diagram of the GitHub repository remix-run/remix, 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/remix-run/remix
- Repository: https://github.com/remix-run/remix

## Overview

Remix 3 is a composable web framework and package ecosystem. Its principal app workflow accepts a Fetch request in a server, routes it to controller actions, and returns a response; actions can render components or serve assets. Separate packages provide data access, authentication, sessions, middleware, and runtime tooling. The README documents these as standalone capabilities composed under the `remix` package. Some package-to-package wiring is not shown in the excerpts, so those relationships are omitted rather than inferred.

Main entry points: [`template/server.ts`](https://github.com/remix-run/remix/blob/main/template/server.ts) (App server), [`packages/remix/src/index.ts`](https://github.com/remix-run/remix/blob/main/packages/remix/src/index.ts) (Remix package), [`template/app/actions/controller.tsx`](https://github.com/remix-run/remix/blob/main/template/app/actions/controller.tsx) (Controller actions), [`packages/data-table/src/lib/database.ts`](https://github.com/remix-run/remix/blob/main/packages/data-table/src/lib/database.ts) (Relational queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Routing and UI"]
  node_router["Fetch router<br/>[router.ts]"]
  node_route_map["Route map<br/>[route-map.ts]"]
  node_controller["Controller actions<br/>[controller.tsx]"]
  node_route_pattern["Route patterns<br/>[program.ts]"]
  node_component_runtime["Component runtime<br/>[render.ts]"]
  node_ui["UI components<br/>[combobox.tsx]"]
end

subgraph group_security["Identity and middleware"]
  node_auth["Auth providers<br/>[provider.ts]"]
  node_auth_middleware["Auth middleware<br/>[auth.ts]"]
  node_session["Session management<br/>[session.ts]"]
  node_session_middleware["Session middleware<br/>[session.ts]"]
  node_security_middleware["Request protections<br/>[csrf.ts]"]
end

subgraph group_data["Data and storage"]
  node_data_schema["Schema validation<br/>[schema.ts]"]
  node_data_table["Relational queries<br/>[database.ts]"]
  node_sql_driver["SQL drivers<br/>[driver.ts]"]
  node_mysql_driver["MySQL adapter<br/>[driver.ts]"]
  node_postgres_driver["Postgres adapter<br/>[driver.ts]"]
  node_sqlite_driver["SQLite adapter<br/>[driver.ts]"]
  node_file_storage["File storage<br/>[file-storage.ts]"]
  node_s3_storage["S3 storage<br/>[s3.ts]"]
end

subgraph group_runtime["Runtime and development"]
  node_app_server["App server<br/>[server.ts]"]
  node_fetch_server["Fetch server<br/>[fetch-handler.ts]"]
  node_component_hmr["Component HMR<br/>[transform.ts]"]
end

subgraph group_tooling["CLI tooling"]
  node_cli["Remix CLI<br/>[cli.ts]"]
  node_routes_command["Routes command<br/>[routes.ts]"]
  node_route_inspection["Route inspection<br/>[route-map.ts]"]
end

subgraph group_distribution["Remix distribution"]
  node_remix_package["Remix package<br/>[index.ts]"]
end

node_developer(("App developer"))
node_http_client(("HTTP client"))
node_node_server["Node server"]

node_developer -.->|"runs commands"| node_cli
node_http_client -.->|"sends request"| node_app_server
node_node_server -->|"runs"| node_app_server
node_app_server -->|"dispatches to"| node_router
node_app_server -.->|"uses"| node_fetch_server
node_router -.->|"routes to"| node_controller
node_controller -->|"uses routes"| node_route_map
node_controller -->|"renders"| node_component_runtime
node_controller -->|"renders page"| node_ui
node_router -.->|"matches paths"| node_route_pattern
node_app_server -.->|"serves actions"| node_controller
node_app_server -.->|"supports refresh"| node_component_hmr
node_cli -.->|"dispatches command"| node_routes_command
node_routes_command -->|"loads route map"| node_route_inspection
node_data_table -.->|"executes operations"| node_sql_driver
node_mysql_driver -->|"adapts toolkit"| node_data_table
node_postgres_driver -->|"adapts toolkit"| node_data_table
node_sqlite_driver -->|"adapts toolkit"| node_data_table
node_s3_storage -.->|"implements backend"| node_file_storage
node_session_middleware -.->|"manages sessions"| node_session
node_auth_middleware -.->|"authenticates with"| node_auth
node_remix_package -.->|"distributes"| node_router
node_remix_package -.->|"distributes"| node_component_runtime
node_remix_package -.->|"distributes"| node_data_table
node_remix_package -.->|"distributes"| node_auth
node_remix_package -.->|"distributes"| node_cli

click node_app_server "https://github.com/remix-run/remix/blob/main/template/server.ts"
click node_fetch_server "https://github.com/remix-run/remix/blob/main/packages/node-fetch-server/src/lib/fetch-handler.ts"
click node_router "https://github.com/remix-run/remix/blob/main/packages/fetch-router/src/lib/router.ts"
click node_route_map "https://github.com/remix-run/remix/blob/main/packages/fetch-router/src/lib/route-map.ts"
click node_controller "https://github.com/remix-run/remix/blob/main/template/app/actions/controller.tsx"
click node_route_pattern "https://github.com/remix-run/remix/blob/main/packages/route-pattern/src/lib/match/program.ts"
click node_component_runtime "https://github.com/remix-run/remix/blob/main/packages/component/src/runtime/render.ts"
click node_component_hmr "https://github.com/remix-run/remix/blob/main/packages/component-hmr/src/lib/transform.ts"
click node_ui "https://github.com/remix-run/remix/blob/main/packages/ui/src/combobox.tsx"
click node_auth "https://github.com/remix-run/remix/blob/main/packages/auth/src/lib/provider.ts"
click node_auth_middleware "https://github.com/remix-run/remix/blob/main/packages/auth-middleware/src/lib/auth.ts"
click node_session "https://github.com/remix-run/remix/blob/main/packages/session/src/lib/session.ts"
click node_session_middleware "https://github.com/remix-run/remix/blob/main/packages/session-middleware/src/lib/session.ts"
click node_security_middleware "https://github.com/remix-run/remix/blob/main/packages/csrf-middleware/src/lib/csrf.ts"
click node_data_schema "https://github.com/remix-run/remix/blob/main/packages/data-schema/src/lib/schema.ts"
click node_data_table "https://github.com/remix-run/remix/blob/main/packages/data-table/src/lib/database.ts"
click node_sql_driver "https://github.com/remix-run/remix/blob/main/packages/data-table/src/lib/driver.ts"
click node_mysql_driver "https://github.com/remix-run/remix/blob/main/packages/data-table-mysql/src/lib/driver.ts"
click node_postgres_driver "https://github.com/remix-run/remix/blob/main/packages/data-table-postgres/src/lib/driver.ts"
click node_sqlite_driver "https://github.com/remix-run/remix/blob/main/packages/data-table-sqlite/src/lib/driver.ts"
click node_file_storage "https://github.com/remix-run/remix/blob/main/packages/file-storage/src/lib/file-storage.ts"
click node_s3_storage "https://github.com/remix-run/remix/blob/main/packages/file-storage-s3/src/lib/s3.ts"
click node_cli "https://github.com/remix-run/remix/blob/main/packages/cli/src/lib/cli.ts"
click node_routes_command "https://github.com/remix-run/remix/blob/main/packages/cli/src/lib/commands/routes.ts"
click node_route_inspection "https://github.com/remix-run/remix/blob/main/packages/cli/src/lib/route-map.ts"
click node_remix_package "https://github.com/remix-run/remix/blob/main/packages/remix/src/index.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_router,node_route_map,node_controller,node_route_pattern,node_component_runtime,node_ui,node_http_client toneBlue
class node_auth,node_auth_middleware,node_session,node_session_middleware,node_security_middleware toneAmber
class node_data_schema,node_data_table,node_sql_driver,node_mysql_driver,node_postgres_driver,node_sqlite_driver,node_file_storage,node_s3_storage,node_node_server toneMint
class node_app_server,node_fetch_server,node_component_hmr toneRose
class node_cli,node_routes_command,node_route_inspection,node_developer toneIndigo
class node_remix_package toneTeal
```

## Components

### Routing and UI

- [Fetch router](https://github.com/remix-run/remix/blob/main/packages/fetch-router/src/lib/router.ts): `packages/fetch-router/src/lib/router.ts`
- [Route map](https://github.com/remix-run/remix/blob/main/packages/fetch-router/src/lib/route-map.ts): `packages/fetch-router/src/lib/route-map.ts`
- [Controller actions](https://github.com/remix-run/remix/blob/main/template/app/actions/controller.tsx): `template/app/actions/controller.tsx`
- [Route patterns](https://github.com/remix-run/remix/blob/main/packages/route-pattern/src/lib/match/program.ts): `packages/route-pattern/src/lib/match/program.ts`
- [Component runtime](https://github.com/remix-run/remix/blob/main/packages/component/src/runtime/render.ts): `packages/component/src/runtime/render.ts`
- [UI components](https://github.com/remix-run/remix/blob/main/packages/ui/src/combobox.tsx): `packages/ui/src/combobox.tsx`

### Identity and middleware

- [Auth providers](https://github.com/remix-run/remix/blob/main/packages/auth/src/lib/provider.ts): `packages/auth/src/lib/provider.ts`
- [Auth middleware](https://github.com/remix-run/remix/blob/main/packages/auth-middleware/src/lib/auth.ts): `packages/auth-middleware/src/lib/auth.ts`
- [Session management](https://github.com/remix-run/remix/blob/main/packages/session/src/lib/session.ts): `packages/session/src/lib/session.ts`
- [Session middleware](https://github.com/remix-run/remix/blob/main/packages/session-middleware/src/lib/session.ts): `packages/session-middleware/src/lib/session.ts`
- [Request protections](https://github.com/remix-run/remix/blob/main/packages/csrf-middleware/src/lib/csrf.ts): `packages/csrf-middleware/src/lib/csrf.ts`

### Data and storage

- [Schema validation](https://github.com/remix-run/remix/blob/main/packages/data-schema/src/lib/schema.ts): `packages/data-schema/src/lib/schema.ts`
- [Relational queries](https://github.com/remix-run/remix/blob/main/packages/data-table/src/lib/database.ts): `packages/data-table/src/lib/database.ts`
- [SQL drivers](https://github.com/remix-run/remix/blob/main/packages/data-table/src/lib/driver.ts): `packages/data-table/src/lib/driver.ts`
- [MySQL adapter](https://github.com/remix-run/remix/blob/main/packages/data-table-mysql/src/lib/driver.ts): `packages/data-table-mysql/src/lib/driver.ts`
- [Postgres adapter](https://github.com/remix-run/remix/blob/main/packages/data-table-postgres/src/lib/driver.ts): `packages/data-table-postgres/src/lib/driver.ts`
- [SQLite adapter](https://github.com/remix-run/remix/blob/main/packages/data-table-sqlite/src/lib/driver.ts): `packages/data-table-sqlite/src/lib/driver.ts`
- [File storage](https://github.com/remix-run/remix/blob/main/packages/file-storage/src/lib/file-storage.ts): `packages/file-storage/src/lib/file-storage.ts`
- [S3 storage](https://github.com/remix-run/remix/blob/main/packages/file-storage-s3/src/lib/s3.ts): `packages/file-storage-s3/src/lib/s3.ts`

### Runtime and development

- [App server](https://github.com/remix-run/remix/blob/main/template/server.ts): `template/server.ts`
- [Fetch server](https://github.com/remix-run/remix/blob/main/packages/node-fetch-server/src/lib/fetch-handler.ts): `packages/node-fetch-server/src/lib/fetch-handler.ts`
- [Component HMR](https://github.com/remix-run/remix/blob/main/packages/component-hmr/src/lib/transform.ts): `packages/component-hmr/src/lib/transform.ts`

### CLI tooling

- [Remix CLI](https://github.com/remix-run/remix/blob/main/packages/cli/src/lib/cli.ts): `packages/cli/src/lib/cli.ts`
- [Routes command](https://github.com/remix-run/remix/blob/main/packages/cli/src/lib/commands/routes.ts): `packages/cli/src/lib/commands/routes.ts`
- [Route inspection](https://github.com/remix-run/remix/blob/main/packages/cli/src/lib/route-map.ts): `packages/cli/src/lib/route-map.ts`

### Remix distribution

- [Remix package](https://github.com/remix-run/remix/blob/main/packages/remix/src/index.ts): `packages/remix/src/index.ts`

### Other components

- **App developer**
- **HTTP client**
- **Node server**

## Connections

- App developer → Remix CLI: runs commands
- HTTP client → App server: sends request
- Node server → App server: runs (evidence: `template/server.ts`)
- App server → Fetch router: dispatches to (evidence: `template/server.ts`)
- App server → Fetch server: uses
- Fetch router → Controller actions: routes to
- Controller actions → Route map: uses routes (evidence: `template/app/actions/controller.tsx`)
- Controller actions → Component runtime: renders (evidence: `template/app/actions/controller.tsx`)
- Controller actions → UI components: renders page (evidence: `template/app/actions/controller.tsx`)
- Fetch router → Route patterns: matches paths
- App server → Controller actions: serves actions
- App server → Component HMR: supports refresh
- Remix CLI → Routes command: dispatches command
- Routes command → Route inspection: loads route map (evidence: `packages/cli/src/lib/commands/routes.ts`)
- Relational queries → SQL drivers: executes operations (evidence: `packages/data-table/src/lib/database.ts`)
- MySQL adapter → Relational queries: adapts toolkit
- Postgres adapter → Relational queries: adapts toolkit
- SQLite adapter → Relational queries: adapts toolkit
- S3 storage → File storage: implements backend
- Session middleware → Session management: manages sessions
- Auth middleware → Auth providers: authenticates with
- Remix package → Fetch router: distributes (evidence: `README.md`)
- Remix package → Component runtime: distributes (evidence: `README.md`)
- Remix package → Relational queries: distributes (evidence: `README.md`)
- Remix package → Auth providers: distributes (evidence: `README.md`)
- Remix package → Remix CLI: distributes (evidence: `README.md`)
