# ripple-ts/ripple architecture

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

- Interactive diagram: https://gitdiagram.com/ripple-ts/ripple
- Repository: https://github.com/ripple-ts/ripple

## Overview

Ripple is a TypeScript-first UI framework for authoring `.tsrx` components, compiling them into fine-grained DOM behavior, and running them in browsers or through server rendering. The main workflow is component authoring → TSRX transformation → Vite integration → client mount or server-rendered response, with hydration connecting server output to browser execution. The README documents reactivity, collections, template control flow, scoped CSS, streaming SSR, and hydration; some plugin, adapter, and compiler wiring is inferred only at subsystem level because their source was not sampled.

Main entry points: [`packages/tsrx-ripple/src/index.js`](https://github.com/ripple-ts/ripple/blob/main/packages/tsrx-ripple/src/index.js) (TSRX compiler), [`packages/vite-plugin/src/index.js`](https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/index.js) (Vite integration), [`packages/adapter/src/index.js`](https://github.com/ripple-ts/ripple/blob/main/packages/adapter/src/index.js) (Adapter interface), [`packages/ripple/src/runtime/internal/client/index.js`](https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/internal/client/index.js) (DOM runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring and compilation"]
  node_tsrx["TSRX compiler<br/>[index.js]"]
  node_client_transform["Client transform<br/>[index.js]"]
  node_server_transform["Server transform<br/>[index.js]"]
  node_ripple_compiler["Ripple compiler<br/>[index.js]"]
end

subgraph group_runtime["Ripple runtime"]
  node_client_entry["Client entry<br/>[index-client.js]"]
  node_client_runtime["DOM runtime<br/>[index.js]"]
  node_reactivity["Reactive state<br/>[reactive-value.js]"]
  node_collections["Reactive collections<br/>[array.js]"]
  node_server_runtime["Server renderer<br/>[index.js]"]
  node_server_api["Server API<br/>[index.js]"]
end

subgraph group_web["Web integration"]
  node_vite_plugin["Vite integration<br/>[index.js]"]
  node_routes["Route definitions<br/>[routes.js]"]
  node_router["Request router<br/>[router.js]"]
  node_render_route["SSR route handler<br/>[render-route.js]"]
  node_server_route["API route handler<br/>[server-route.js]"]
  node_stream_response["Stream response<br/>[stream-response.js]"]
  node_adapter["Adapter interface<br/>[index.js]"]
  node_node_adapter["Node adapter<br/>[index.js]"]
  node_bun_adapter["Bun adapter<br/>[index.js]"]
  node_vercel_adapter["Vercel adapter<br/>[index.js]"]
end

subgraph group_setup["Project setup"]
  node_creator["Project creator<br/>[index.js]"]
  node_cli["CLI commands<br/>[create.js]"]
end

node_developer(("Application developer"))
node_app_code["TSRX application"]
node_browser(("Browser"))
node_http_client(("HTTP client"))

node_developer -->|"authors"| node_app_code
node_app_code -->|"compiles"| node_tsrx
node_tsrx -->|"transforms client"| node_client_transform
node_tsrx -->|"transforms server"| node_server_transform
node_app_code -->|"integrates via"| node_vite_plugin
node_vite_plugin -->|"invokes compiler"| node_tsrx
node_client_entry -->|"renders components"| node_client_runtime
node_client_runtime -->|"tracks state"| node_reactivity
node_client_runtime -->|"exposes collections"| node_collections
node_browser -->|"mounts or hydrates"| node_client_entry
node_server_api -->|"renders components"| node_server_runtime
node_vite_plugin -->|"registers routes"| node_routes
node_routes -->|"supplies route table"| node_router
node_router -->|"dispatches render"| node_render_route
node_router -->|"dispatches API"| node_server_route
node_render_route -->|"renders page"| node_server_api
node_render_route -->|"builds response"| node_stream_response
node_http_client -->|"sends request"| node_vite_plugin
node_adapter -.->|"implemented by"| node_node_adapter
node_adapter -.->|"implemented by"| node_bun_adapter
node_adapter -.->|"implemented by"| node_vercel_adapter
node_developer -->|"creates project"| node_cli
node_cli -->|"delegates creation"| node_creator

click node_tsrx "https://github.com/ripple-ts/ripple/blob/main/packages/tsrx-ripple/src/index.js"
click node_client_transform "https://github.com/ripple-ts/ripple/blob/main/packages/tsrx-ripple/src/transform/client/index.js"
click node_server_transform "https://github.com/ripple-ts/ripple/blob/main/packages/tsrx-ripple/src/transform/server/index.js"
click node_ripple_compiler "https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/compiler/index.js"
click node_vite_plugin "https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/index.js"
click node_routes "https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/routes.js"
click node_router "https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/server/router.js"
click node_render_route "https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/server/render-route.js"
click node_server_route "https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/server/server-route.js"
click node_stream_response "https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/server/stream-response.js"
click node_adapter "https://github.com/ripple-ts/ripple/blob/main/packages/adapter/src/index.js"
click node_node_adapter "https://github.com/ripple-ts/ripple/blob/main/packages/adapter-node/src/index.js"
click node_bun_adapter "https://github.com/ripple-ts/ripple/blob/main/packages/adapter-bun/src/index.js"
click node_vercel_adapter "https://github.com/ripple-ts/ripple/blob/main/packages/adapter-vercel/src/index.js"
click node_client_entry "https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/index-client.js"
click node_client_runtime "https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/internal/client/index.js"
click node_reactivity "https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/reactive-value.js"
click node_collections "https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/array.js"
click node_server_runtime "https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/internal/server/index.js"
click node_server_api "https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/server/index.js"
click node_creator "https://github.com/ripple-ts/ripple/blob/main/packages/create-ripple/src/index.js"
click node_cli "https://github.com/ripple-ts/ripple/blob/main/packages/cli/src/commands/create.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_tsrx,node_client_transform,node_server_transform,node_ripple_compiler,node_browser,node_http_client toneBlue
class node_client_entry,node_client_runtime,node_reactivity,node_collections,node_server_runtime,node_server_api toneAmber
class node_vite_plugin,node_routes,node_router,node_render_route,node_server_route,node_stream_response,node_adapter,node_node_adapter,node_bun_adapter,node_vercel_adapter toneMint
class node_creator,node_cli toneRose
class node_developer,node_app_code toneIndigo
```

## Components

### Authoring and compilation

- [TSRX compiler](https://github.com/ripple-ts/ripple/blob/main/packages/tsrx-ripple/src/index.js): `packages/tsrx-ripple/src/index.js`
- [Client transform](https://github.com/ripple-ts/ripple/blob/main/packages/tsrx-ripple/src/transform/client/index.js): `packages/tsrx-ripple/src/transform/client/index.js`
- [Server transform](https://github.com/ripple-ts/ripple/blob/main/packages/tsrx-ripple/src/transform/server/index.js): `packages/tsrx-ripple/src/transform/server/index.js`
- [Ripple compiler](https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/compiler/index.js): `packages/ripple/src/compiler/index.js`

### Ripple runtime

- [Client entry](https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/index-client.js): `packages/ripple/src/runtime/index-client.js`
- [DOM runtime](https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/internal/client/index.js): `packages/ripple/src/runtime/internal/client/index.js`
- [Reactive state](https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/reactive-value.js): `packages/ripple/src/runtime/reactive-value.js`
- [Reactive collections](https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/array.js): `packages/ripple/src/runtime/array.js`
- [Server renderer](https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/runtime/internal/server/index.js): `packages/ripple/src/runtime/internal/server/index.js`
- [Server API](https://github.com/ripple-ts/ripple/blob/main/packages/ripple/src/server/index.js): `packages/ripple/src/server/index.js`

### Web integration

- [Vite integration](https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/index.js): `packages/vite-plugin/src/index.js`
- [Route definitions](https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/routes.js): `packages/vite-plugin/src/routes.js`
- [Request router](https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/server/router.js): `packages/vite-plugin/src/server/router.js`
- [SSR route handler](https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/server/render-route.js): `packages/vite-plugin/src/server/render-route.js`
- [API route handler](https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/server/server-route.js): `packages/vite-plugin/src/server/server-route.js`
- [Stream response](https://github.com/ripple-ts/ripple/blob/main/packages/vite-plugin/src/server/stream-response.js): `packages/vite-plugin/src/server/stream-response.js`
- [Adapter interface](https://github.com/ripple-ts/ripple/blob/main/packages/adapter/src/index.js): `packages/adapter/src/index.js`
- [Node adapter](https://github.com/ripple-ts/ripple/blob/main/packages/adapter-node/src/index.js): `packages/adapter-node/src/index.js`
- [Bun adapter](https://github.com/ripple-ts/ripple/blob/main/packages/adapter-bun/src/index.js): `packages/adapter-bun/src/index.js`
- [Vercel adapter](https://github.com/ripple-ts/ripple/blob/main/packages/adapter-vercel/src/index.js): `packages/adapter-vercel/src/index.js`

### Project setup

- [Project creator](https://github.com/ripple-ts/ripple/blob/main/packages/create-ripple/src/index.js): `packages/create-ripple/src/index.js`
- [CLI commands](https://github.com/ripple-ts/ripple/blob/main/packages/cli/src/commands/create.js): `packages/cli/src/commands/create.js`

### Other components

- **Application developer**
- **TSRX application**
- **Browser**
- **HTTP client**

## Connections

- Application developer → TSRX application: authors
- TSRX application → TSRX compiler: compiles
- TSRX compiler → Client transform: transforms client
- TSRX compiler → Server transform: transforms server
- TSRX application → Vite integration: integrates via
- Vite integration → TSRX compiler: invokes compiler
- Client entry → DOM runtime: renders components
- DOM runtime → Reactive state: tracks state
- DOM runtime → Reactive collections: exposes collections
- Browser → Client entry: mounts or hydrates
- Server API → Server renderer: renders components
- Vite integration → Route definitions: registers routes
- Route definitions → Request router: supplies route table
- Request router → SSR route handler: dispatches render
- Request router → API route handler: dispatches API
- SSR route handler → Server API: renders page
- SSR route handler → Stream response: builds response
- HTTP client → Vite integration: sends request
- Adapter interface → Node adapter: implemented by
- Adapter interface → Bun adapter: implemented by
- Adapter interface → Vercel adapter: implemented by
- Application developer → CLI commands: creates project
- CLI commands → Project creator: delegates creation