# toss/suspensive architecture

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

- Interactive diagram: https://gitdiagram.com/toss/suspensive
- Repository: https://github.com/toss/suspensive

## Overview

##### Project Type and Purpose
- This is an open-source monorepo of TypeScript/JavaScript libraries (“Suspensive”) providing utilities and integration points to use React Suspense easily across React, React DOM, React Native, React Query (v4 & v5), Jotai, plus codemods.
- It also includes a Next.js-based documentation website (`docs/suspensive.org`) and several example consumer apps under `examples/`.
- Tooling is centralized via pnpm workspaces and Turborepo; builds use tsup; tests use Vitest/Jest; CI/CD runs via GitHub Actions; publishing targets the npm registry.

##### File Structure Analysis
Top-level directories:
- `.github/`, `ci.yml`, etc. → CI/CD and repository automation
- `configs/` → shared ESLint, tsconfig, tsup configurations packaged for intra-repo reuse
- `packages/` → eight workspace packages (codemods, jotai, react-dom, react-native, react-query-4, react-query-5, react-query, react) each with `src/`, tests, build configs
- `docs/suspensive.org/` → Next.js website with MDX pages, components, static assets
- `examples/` → example consumer projects demonstrating usage patterns
- Root scripts & config: `pnpm-workspace.yaml`, `turbo.json`, `package.json`, lint/staged, husky, commitlint, Codecov, Dependabot, etc.

##### Key README Insights
- “All in one for React Suspense” – the monorepo produces multiple related packages.
- Documentation is delivered via `suspensive.org` (Next.js site under `docs/`).
- CI badges (Codecov, GitHub Actions workflows for lint, test, graph, release).

A. Workspace Manager
- pnpm workspaces & Turborepo orchestrate installation and task pipelines.
B. Shared Configuration Packages (`configs/`)
- ESLint configs, tsconfig presets, tsup configs → consumed by each package, example, docs.
C. Library Packages (`packages/*`)
- codemods
- jotai
- react
- react-dom
- react-native
- react-query-4 & react-query-5 & react-query (CLI tooling)
– Each package: `src/` → build (tsup) → `dist/` → published to npm.
D. Documentation Site (`docs/suspensive.org`)
- Next.js app → MDX content + React components → hosted on suspensive.org
- Imports versioned packages, example code embeds.
E. Example Applications (`examples/*`)
- Next.js examples, React Native playground, Vite/React example → install workspace packages → showcase features.
F. CI/CD & Publishing
- GitHub Actions workflows trigger on push/PR:
– Lint & typecheck → tests → code coverage → graph dependencies → knip (unused imports)
– On release tag: Turborepo publishes packages to npm, updates docs site.
- External services: GitHub, Codecov, npm registry, Discord link.

Relationships & Data Flows:
1. Developer commits → Husky + lint-staged + commitlint validate code locally.
2. Push triggers GitHub Actions → Turborepo runs tasks in workspace.
3. Package build → tsup bundles each package → Vitest/Jest picks up tests → Codecov collects coverage.
4. On release: packages published to npm; docs site deployed.
5. Examples & docs `npm install` pull from local workspace during development or from npm in CI.

##### Architectural Patterns & Principles
- Monorepo with Workspace Isolation: shared config, enforced by pnpm + Turborepo caching.
- Modular Design: each package is standalone, versioned, tested, and published independently.
- Reuse of Shared Config: ESLint, tsconfig, tsup configs are themselves packages under `configs/`.
- Consumer-Driven Documentation & Examples: docs site and examples import directly from workspace during dev, ensuring up-to-date demos.
- CI as Code: GitHub workflows defined centrally under `.github/`.

## Diagram (Mermaid)

```mermaid
flowchart TD
  Dev["Developer"]:::workspace
  Dev --> Monorepo

  subgraph "Suspensive Monorepo"
    subgraph "Workspace Manager"
      WM["pnpm & Turborepo"]:::workspace
    end

    subgraph "Shared Config Packages"
      ESLint["ESLint Config"]:::config
      TSConfig["TypeScript Configs"]:::config
      TSUP["tsup Config"]:::config
    end

    subgraph "Library Packages"
      Codemods["codemods"]:::lib
      Jotai["jotai integration"]:::lib
      ReactCore["React core utilities"]:::lib
      ReactDOM["React DOM utilities"]:::lib
      ReactNative["React Native utilities"]:::lib
      RQ4["React Query v4 adapter"]:::lib
      RQ5["React Query v5 adapter"]:::lib
      RQCLI["React Query CLI/tooling"]:::lib
    end

    subgraph "Documentation Site"
      Docs["Next.js Docs Site"]:::docs
    end

    subgraph "Example Applications"
      Ex1["Next.js Streaming + React Query"]:::examples
      Ex2["React Native Playground"]:::examples
      Ex3["Visualization (Vite/Next)"]:::examples
      Ex4["Vite React 18 Suspense Prerender"]:::examples
    end

    subgraph "CI/CD & Automation"
      GHWorkflows["GitHub Actions workflows"]:::ci
      CustomAction["pnpm-setup-node Action"]:::ci
      Husky["Husky hooks"]:::ci
      LintStaged["lint-staged config"]:::ci
      CommitLint["Commitlint config"]:::ci
      Codecov["Codecov integration"]:::ci
    end

    NPM["npm Registry"]:::external

  end

  %% Config consumption
  ESLint -->|consumed by| Codemods
  ESLint -->|consumed by| Jotai
  ESLint -->|consumed by| ReactCore
  ESLint -->|consumed by| ReactDOM
  ESLint -->|consumed by| ReactNative
  ESLint -->|consumed by| RQ4
  ESLint -->|consumed by| RQ5
  ESLint -->|consumed by| RQCLI
  ESLint -->|consumed by| Docs
  ESLint -->|consumed by| Ex1

  TSConfig -->|consumed by| Codemods
  TSConfig -->|consumed by| Jotai
  TSConfig -->|consumed by| ReactCore
  TSConfig -->|consumed by| ReactDOM
  TSConfig -->|consumed by| ReactNative
  TSConfig -->|consumed by| RQ4
  TSConfig -->|consumed by| RQ5
  TSConfig -->|consumed by| RQCLI
  TSConfig -->|consumed by| Docs
  TSConfig -->|consumed by| Ex1

  TSUP -->|consumed by| Codemods
  TSUP -->|consumed by| Jotai
  TSUP -->|consumed by| ReactCore
  TSUP -->|consumed by| ReactDOM
  TSUP -->|consumed by| ReactNative
  TSUP -->|consumed by| RQ4
  TSUP -->|consumed by| RQ5
  TSUP -->|consumed by| RQCLI
  TSUP -->|consumed by| Docs
  TSUP -->|consumed by| Ex1

  %% Package build/test/publish
  WM -->|build| Codemods
  WM -->|build| Jotai
  WM -->|build| ReactCore
  WM -->|build| ReactDOM
  WM -->|build| ReactNative
  WM -->|build| RQ4
  WM -->|build| RQ5
  WM -->|build| RQCLI

  WM -->|test| Codemods
  WM -->|test| Jotai
  WM -->|test| ReactCore
  WM -->|test| ReactDOM
  WM -->|test| ReactNative
  WM -->|test| RQ4
  WM -->|test| RQ5
  WM -->|test| RQCLI

  WM -->|publish| NPM

  %% Docs & Examples consumption
  Docs -->|imports| Codemods
  Docs -->|imports| Jotai
  Docs -->|imports| ReactCore
  Docs -->|imports| ReactDOM
  Docs -->|imports| ReactNative
  Docs -->|imports| RQ4
  Docs -->|imports| RQ5
  Docs -->|imports| RQCLI

  Ex1 -->|uses| Codemods
  Ex1 -->|uses| Jotai
  Ex1 -->|uses| ReactCore
  Ex1 -->|uses| ReactDOM
  Ex1 -->|uses| RQ4
  Ex1 -->|uses| RQCLI

  Ex2 -->|uses| ReactNative
  Ex2 -->|uses| ReactCore

  Ex3 -->|uses| ReactCore
  Ex3 -->|uses| ReactDOM

  Ex4 -->|uses| ReactCore
  Ex4 -->|uses| ReactDOM

  %% CI/CD workflow
  Dev -->|push| GHWorkflows
  GHWorkflows -->|run| WM
  GHWorkflows -->|run| Husky
  GHWorkflows -->|run| LintStaged
  GHWorkflows -->|run| CommitLint
  GHWorkflows -->|run tests| WM
  GHWorkflows -->|collect coverage| Codecov
  GHWorkflows -->|on release| WM
  GHWorkflows -->|deploy docs| Docs

  %% Styles
  classDef config fill:#bbe1fa,stroke:#3282b8,color:#0f4c75;
  classDef lib fill:#d5f5e3,stroke:#379237,color:#145214;
  classDef docs fill:#ffd8a9,stroke:#e89600,color:#7a4900;
  classDef examples fill:#ffe3e3,stroke:#e85d75,color:#7a2535;
  classDef ci fill:#e0bbff,stroke:#8a2be2,color:#4b0082;
  classDef workspace fill:#fce1a8,stroke:#f5a623,color:#4e3b31;
  classDef external fill:#cccccc,stroke:#888888,color:#444444;

  %% Click Events
  click WM "https://github.com/toss/suspensive/blob/main/pnpm-workspace.yaml"
  click WM "https://github.com/toss/suspensive/blob/main/turbo.json"
  click ESLint "https://github.com/toss/suspensive/tree/main/configs/eslint-config/"
  click TSConfig "https://github.com/toss/suspensive/tree/main/configs/tsconfig/"
  click TSUP "https://github.com/toss/suspensive/tree/main/configs/tsup/"
  click Codemods "https://github.com/toss/suspensive/tree/main/packages/codemods/"
  click Jotai "https://github.com/toss/suspensive/tree/main/packages/jotai/"
  click ReactCore "https://github.com/toss/suspensive/tree/main/packages/react/"
  click ReactDOM "https://github.com/toss/suspensive/tree/main/packages/react-dom/"
  click ReactNative "https://github.com/toss/suspensive/tree/main/packages/react-native/"
  click RQ4 "https://github.com/toss/suspensive/tree/main/packages/react-query-4/"
  click RQ5 "https://github.com/toss/suspensive/tree/main/packages/react-query-5/"
  click RQCLI "https://github.com/toss/suspensive/tree/main/packages/react-query/"
  click Docs "https://github.com/toss/suspensive/tree/main/docs/suspensive.org/"
  click Ex1 "https://github.com/toss/suspensive/tree/main/examples/next-streaming-react-query/"
  click Ex2 "https://github.com/toss/suspensive/tree/main/examples/react-native-playground/"
  click Ex3 "https://github.com/toss/suspensive/tree/main/examples/visualization/"
  click Ex4 "https://github.com/toss/suspensive/tree/main/examples/vite-react-18-suspense-prerender-siblings-problem/"
  click GHWorkflows "https://github.com/toss/suspensive/tree/main/.github/workflows/"
  click CustomAction "https://github.com/toss/suspensive/tree/main/.github/actions/pnpm-setup-node/"
  click Husky "https://github.com/toss/suspensive/tree/main/.husky/"
  click LintStaged "https://github.com/toss/suspensive/blob/main/.lintstagedrc"
  click CommitLint "https://github.com/toss/suspensive/blob/main/commitlint.config.mjs"
  click Codecov "https://github.com/toss/suspensive/blob/main/codecov.yml"
```
