# raine-works/rainestack architecture

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

- Interactive diagram: https://gitdiagram.com/raine-works/rainestack
- Repository: https://github.com/raine-works/rainestack

## Overview

RaineStack is a full-stack TypeScript monorepo starter: a React web shell calls a typed oRPC API served by Bun, with PostgreSQL/Prisma-backed data and authentication. The main user workflow is browser entry → routed home experience, while application API requests pass through the server to domain routes and database operations. The graph also preserves actor-audited transactions, database change notifications, shared UI, and API-client infrastructure. Relationships are limited to those shown in excerpts, SOURCE INDEX references, or README statements; unsampled subsystems are not expanded.

Main entry points: [`packages/server/src/routes/auth.ts`](https://github.com/raine-works/rainestack/blob/master/packages/server/src/routes/auth.ts) (Authentication routes), [`packages/database/src/index.ts`](https://github.com/raine-works/rainestack/blob/master/packages/database/src/index.ts) (Prisma database), [`packages/web/src/main.tsx`](https://github.com/raine-works/rainestack/blob/master/packages/web/src/main.tsx) (Web entry), [`packages/server/src/index.ts`](https://github.com/raine-works/rainestack/blob/master/packages/server/src/index.ts) (Bun HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_web_entry["Web entry<br/>[main.tsx]"]
  node_web_app["App routing<br/>[app.tsx]"]
  node_home["Home page<br/>[home.tsx]"]
  node_web_api["Web API client<br/>[api.ts]"]
  node_shared_ui["UI library"]
  node_query_provider["Query provider<br/>[query-provider.tsx]"]
end

subgraph group_api["API and server"]
  node_api_client["Typed API client<br/>[index.ts]"]
  node_api_contract["Router type bridge<br/>[router.ts]"]
  node_http_server["Bun HTTP server<br/>[index.ts]"]
end

subgraph group_authdata["Authentication and data"]
  node_auth_middleware["JWT middleware<br/>[auth.ts]"]
  node_auth_routes["Authentication routes<br/>[auth.ts]"]
  node_auth_data["Auth data access<br/>[passkeys.ts]"]
  node_domain_data["Domain data"]
end

subgraph group_persistence["Database infrastructure"]
  node_prisma_db[("Prisma database<br/>[index.ts]")]
  node_actor_tx["Actor transactions<br/>[actor.ts]"]
  node_change_listener["Change listener<br/>[listener.ts]"]
end

node_visitor(("Browser visitor"))
node_postgres[("PostgreSQL")]

node_visitor -->|"opens app"| node_web_entry
node_web_entry -->|"mounts"| node_web_app
node_web_entry -->|"wraps with"| node_query_provider
node_web_entry -->|"renders toaster"| node_shared_ui
node_web_app -->|"routes to"| node_home
node_home -->|"renders"| node_shared_ui
node_web_api -->|"uses"| node_api_client
node_query_provider -.->|"provides queries"| node_api_client
node_api_client -->|"types against"| node_api_contract
node_api_contract -->|"exports router type"| node_http_server
node_http_server -->|"dispatches API"| node_auth_routes
node_http_server -->|"checks database"| node_prisma_db
node_http_server -->|"connects listener"| node_change_listener
node_auth_routes -.->|"uses auth"| node_auth_middleware
node_auth_routes -->|"calls passkey data"| node_auth_data
node_auth_routes -->|"queries accounts"| node_prisma_db
node_auth_routes -->|"uses account data"| node_domain_data
node_auth_routes -->|"tracks mutations"| node_actor_tx
node_auth_data -->|"wraps writes"| node_actor_tx
node_auth_data -->|"reads and writes"| node_prisma_db
node_actor_tx -->|"runs transactions"| node_prisma_db
node_prisma_db -->|"persists data"| node_postgres
node_change_listener -->|"listens for changes"| node_postgres

click node_web_entry "https://github.com/raine-works/rainestack/blob/master/packages/web/src/main.tsx"
click node_web_app "https://github.com/raine-works/rainestack/blob/master/packages/web/src/app.tsx"
click node_home "https://github.com/raine-works/rainestack/blob/master/packages/web/src/routes/home.tsx"
click node_web_api "https://github.com/raine-works/rainestack/blob/master/packages/web/src/lib/api.ts"
click node_shared_ui "https://github.com/raine-works/rainestack/tree/master/packages/ui/src/components/ui"
click node_query_provider "https://github.com/raine-works/rainestack/blob/master/packages/api/src/lib/query-provider.tsx"
click node_api_client "https://github.com/raine-works/rainestack/blob/master/packages/api/src/index.ts"
click node_api_contract "https://github.com/raine-works/rainestack/blob/master/packages/api/src/router.ts"
click node_http_server "https://github.com/raine-works/rainestack/blob/master/packages/server/src/index.ts"
click node_auth_middleware "https://github.com/raine-works/rainestack/blob/master/packages/server/src/lib/auth.ts"
click node_auth_routes "https://github.com/raine-works/rainestack/blob/master/packages/server/src/routes/auth.ts"
click node_auth_data "https://github.com/raine-works/rainestack/blob/master/packages/server/src/data/passkeys.ts"
click node_domain_data "https://github.com/raine-works/rainestack/tree/master/packages/server/src/data"
click node_prisma_db "https://github.com/raine-works/rainestack/blob/master/packages/database/src/index.ts"
click node_actor_tx "https://github.com/raine-works/rainestack/blob/master/packages/database/src/actor.ts"
click node_change_listener "https://github.com/raine-works/rainestack/blob/master/packages/database/src/listener.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_web_entry,node_web_app,node_home,node_web_api,node_shared_ui,node_query_provider,node_visitor toneBlue
class node_api_client,node_api_contract,node_http_server,node_postgres toneAmber
class node_auth_middleware,node_auth_routes,node_auth_data,node_domain_data toneMint
class node_prisma_db,node_actor_tx,node_change_listener toneRose
```

## Components

### Web application

- [Web entry](https://github.com/raine-works/rainestack/blob/master/packages/web/src/main.tsx): `packages/web/src/main.tsx`
- [App routing](https://github.com/raine-works/rainestack/blob/master/packages/web/src/app.tsx): `packages/web/src/app.tsx`
- [Home page](https://github.com/raine-works/rainestack/blob/master/packages/web/src/routes/home.tsx): `packages/web/src/routes/home.tsx`
- [Web API client](https://github.com/raine-works/rainestack/blob/master/packages/web/src/lib/api.ts): `packages/web/src/lib/api.ts`
- [UI library](https://github.com/raine-works/rainestack/tree/master/packages/ui/src/components/ui): `packages/ui/src/components/ui`
- [Query provider](https://github.com/raine-works/rainestack/blob/master/packages/api/src/lib/query-provider.tsx): `packages/api/src/lib/query-provider.tsx`

### API and server

- [Typed API client](https://github.com/raine-works/rainestack/blob/master/packages/api/src/index.ts): `packages/api/src/index.ts`
- [Router type bridge](https://github.com/raine-works/rainestack/blob/master/packages/api/src/router.ts): `packages/api/src/router.ts`
- [Bun HTTP server](https://github.com/raine-works/rainestack/blob/master/packages/server/src/index.ts): `packages/server/src/index.ts`

### Authentication and data

- [JWT middleware](https://github.com/raine-works/rainestack/blob/master/packages/server/src/lib/auth.ts): `packages/server/src/lib/auth.ts`
- [Authentication routes](https://github.com/raine-works/rainestack/blob/master/packages/server/src/routes/auth.ts): `packages/server/src/routes/auth.ts`
- [Auth data access](https://github.com/raine-works/rainestack/blob/master/packages/server/src/data/passkeys.ts): `packages/server/src/data/passkeys.ts`
- [Domain data](https://github.com/raine-works/rainestack/tree/master/packages/server/src/data): `packages/server/src/data`

### Database infrastructure

- [Prisma database](https://github.com/raine-works/rainestack/blob/master/packages/database/src/index.ts): `packages/database/src/index.ts`
- [Actor transactions](https://github.com/raine-works/rainestack/blob/master/packages/database/src/actor.ts): `packages/database/src/actor.ts`
- [Change listener](https://github.com/raine-works/rainestack/blob/master/packages/database/src/listener.ts): `packages/database/src/listener.ts`

### Other components

- **Browser visitor**
- **PostgreSQL**

## Connections

- Browser visitor → Web entry: opens app (evidence: `packages/web/src/main.tsx`)
- Web entry → App routing: mounts (evidence: `packages/web/src/main.tsx`)
- Web entry → Query provider: wraps with (evidence: `packages/web/src/main.tsx`)
- Web entry → UI library: renders toaster (evidence: `packages/web/src/main.tsx`)
- App routing → Home page: routes to (evidence: `packages/web/src/app.tsx`)
- Home page → UI library: renders (evidence: `packages/web/src/routes/home.tsx`)
- Web API client → Typed API client: uses (evidence: `packages/web/src/lib/api.ts`)
- Query provider → Typed API client: provides queries
- Typed API client → Router type bridge: types against (evidence: `packages/api/src/router.ts`)
- Router type bridge → Bun HTTP server: exports router type (evidence: `packages/api/src/router.ts`)
- Bun HTTP server → Authentication routes: dispatches API (evidence: `packages/server/src/index.ts`)
- Bun HTTP server → Prisma database: checks database (evidence: `packages/server/src/index.ts`)
- Bun HTTP server → Change listener: connects listener (evidence: `packages/server/src/index.ts`)
- Authentication routes → JWT middleware: uses auth
- Authentication routes → Auth data access: calls passkey data (evidence: `packages/server/src/routes/auth.ts`)
- Authentication routes → Prisma database: queries accounts (evidence: `packages/server/src/routes/auth.ts`)
- Authentication routes → Domain data: uses account data (evidence: `packages/server/src/routes/auth.ts`)
- Authentication routes → Actor transactions: tracks mutations (evidence: `packages/server/src/routes/auth.ts`)
- Auth data access → Actor transactions: wraps writes (evidence: `packages/server/src/data/passkeys.ts`)
- Auth data access → Prisma database: reads and writes (evidence: `packages/server/src/data/passkeys.ts`)
- Actor transactions → Prisma database: runs transactions
- Prisma database → PostgreSQL: persists data (evidence: `packages/database/src/index.ts`)
- Change listener → PostgreSQL: listens for changes (evidence: `packages/database/src/listener.ts`)