# reactplay/react-play architecture

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

- Interactive diagram: https://gitdiagram.com/reactplay/react-play
- Repository: https://github.com/reactplay/react-play

## Overview

##### Project Type and Purpose
- This is an open-source, full-frontend ReactJS web application (“ReactPlay”) that aggregates dozens of small hands-on React projects (“plays”), offers user contributions, and displays dynamic content (contributors, badges, plays, testimonials, etc.).
- It runs entirely in the browser, communicates with external services (GitHub APIs, Nhost/Hasura backend for data and auth), and is deployed via Netlify/Vercel or Docker.

##### File Structure
- Top-level: build & config files (Dockerfile, docker-compose, Netlify.toml, ESLint/Prettier, GitHub workflows).
- `/public` & `/src`: React App code.
- `/src/common`: shared UI components, hooks, routing, and service-layer functions.
- `/src/plays`: individual mini-apps (“plays”) each self-contained.
- `/src/services`: HTTP request layer to external APIs.
- E2E tests under `/e2e` using Playwright.
- CI/CD workflows in `.github/workflows`.

##### README for Insights
- Uses React 18, Yarn/PNPM, Husky for pre-commit hooks.
- Environment config via `.env.development` (Nhost, GitHub tokens).
- Deployable to Netlify or Vercel.
- E2E via Playwright.
- Emphasizes contributor workflow for adding new “plays.”

##### Main Components & Relationships
a. Frontend (React SPA)
- Core App shell (`src/index.jsx` → `App.jsx`).
- Shared components & utilities (`src/common`).
- Play modules under `src/plays/*`.
- Routing layer directs URL paths to plays or common pages (404, ErrorBoundary).
b. Services/Backend
- GitHub REST/GraphQL APIs (contributors, issues).
- Nhost/Hasura POST endpoints (badges, plays metadata, testimonials).
- Other third-party APIs (e.g. YouTube Embed, Unsplash).
c. External Tools
- Playwright (E2E).
- CI/CD: GitHub Actions for lint, tests, release drafting.
- Docker & docker-compose for local dev/prod containers.
- Netlify/Vercel for hosting.

##### Architectural Patterns & Principles
- Component-based design: each “play” is isolated.
- Service-oriented API layer: `common/services/request/query/*` separates HTTP concerns.
- Hooks for shared state & caching (`useFetch`, `useCacheResponse`).
- Centralized routing (`RouteDefs.jsx`).
- Error boundaries for robust UI (`ErrorBoundary`).
- CI/CD pipelines for quality gates.

##### Detailed Coverage
- That each “play” folder is a self-contained React component loaded via routing.
- Service queries (e.g. `fetch-plays-paginated.js`) as part of the API layer.
- E2E tests launching against the local/dev Docker container.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser/Client"
        subgraph "React SPA"
            AppShell["App Shell"]:::internal
            Routing["Router"]:::internal
            ErrorBoundary["Error Boundary"]:::internal
            SharedUI["Shared UI Components"]:::internal
            SharedHooks["Hooks & Utilities"]:::internal
            ServiceLayer["Service Layer"]:::internal
            EnvConfig["Config (.env & netlify.toml)"]:::internal
            Plays["Individual Play Modules"]:::internal
            Meta["Metadata & SEO"]:::internal
        end
    end

    subgraph "External APIs & Services"
        GitHub["GitHub API"]:::external
        Nhost["Nhost/Hasura Backend"]:::external
        PublicAPI["Other Public APIs"]:::external
    end

    subgraph "CI/CD & Infrastructure"
        Actions["GitHub Actions"]:::cicd
        E2E["Playwright E2E Tests"]:::cicd
        Docker["Docker (Dev/Prod)"]:::infra
        Netlify["Netlify/Vercel"]:::infra
    end

    User["User"]:::external -->|uses| AppShell
    AppShell -->|mounts| Routing
    AppShell -->|wraps| ErrorBoundary
    Routing -->|renders| Plays
    Routing -->|renders| SharedUI
    AppShell -->|imports| SharedHooks
    SharedHooks -->|used by| ServiceLayer
    ServiceLayer -->|calls| GitHub
    ServiceLayer -->|calls| Nhost
    ServiceLayer -->|calls| PublicAPI
    AppShell -->|loads| EnvConfig
    AppShell -->|includes| Meta
    Actions -->|runs| Docker
    Actions -->|triggers| E2E
    Docker -->|deploys to| Netlify
    E2E -->|tests on| Docker

    classDef internal fill:#D0E8FF,stroke:#3B82F6,color:#1E3A8A
    classDef external fill:#D1FAE5,stroke:#10B981,color:#065F46
    classDef cicd fill:#FFEDD5,stroke:#F97316,color:#7C2D12
    classDef infra fill:#E5E7EB,stroke:#6B7280,color:#374151

    click AppShell "https://github.com/reactplay/react-play/blob/main/src/index.jsx"
    click AppShell "https://github.com/reactplay/react-play/blob/main/src/App.jsx"
    click ErrorBoundary "https://github.com/reactplay/react-play/blob/main/src/ErrorBoundary/ErrorBoundary.jsx"
    click ErrorBoundary "https://github.com/reactplay/react-play/blob/main/src/ErrorBoundary/ErrorFallback.jsx"
    click SharedUI "https://github.com/reactplay/react-play/tree/main/src/common/components"
    click SharedUI "https://github.com/reactplay/react-play/tree/main/src/common/home"
    click SharedUI "https://github.com/reactplay/react-play/tree/main/src/common/footer"
    click SharedUI "https://github.com/reactplay/react-play/tree/main/src/common/header"
    click SharedUI "https://github.com/reactplay/react-play/tree/main/src/common/playlists"
    click SharedUI "https://github.com/reactplay/react-play/blob/main/src/common/404/PageNotFound.jsx"
    click SharedHooks "https://github.com/reactplay/react-play/tree/main/src/common/hooks"
    click SharedHooks "https://github.com/reactplay/react-play/tree/main/src/common/utils"
    click Routing "https://github.com/reactplay/react-play/blob/main/src/common/routing/RouteDefs.jsx"
    click Routing "https://github.com/reactplay/react-play/blob/main/src/common/routing/hooks/useLocationChange.js"
    click ServiceLayer "https://github.com/reactplay/react-play/blob/main/src/common/services/request/query/fetch-plays-paginated.js"
    click ServiceLayer "https://github.com/reactplay/react-play/blob/main/src/common/services/request/query/like-play.js"
    click ServiceLayer "https://github.com/reactplay/react-play/blob/main/src/common/services/request/query/testimonials.js"
    click ServiceLayer "https://github.com/reactplay/react-play/blob/main/src/common/services/index.js"
    click EnvConfig "https://github.com/reactplay/react-play/blob/main/.env.development"
    click EnvConfig "https://github.com/reactplay/react-play/blob/main/netlify.toml"
    click Plays "https://github.com/reactplay/react-play/tree/main/src/plays"
    click Meta "https://github.com/reactplay/react-play/blob/main/src/meta/DefMeta.jsx"
    click Meta "https://github.com/reactplay/react-play/blob/main/src/meta/play-meta-util.js"
    click E2E "https://github.com/reactplay/react-play/tree/main/e2e/pageobjects"
    click E2E "https://github.com/reactplay/react-play/tree/main/e2e/tests"
    click E2E "https://github.com/reactplay/react-play/blob/main/playwright.config.ts"
    click Actions "https://github.com/reactplay/react-play/blob/main/.github/workflows/playwright-e2e.yml"
    click Actions "https://github.com/reactplay/react-play/blob/main/.github/workflows/release-drafter.yml"
    click Docker "https://github.com/reactplay/react-play/blob/main/Dockerfile.DEV"
    click Docker "https://github.com/reactplay/react-play/blob/main/Dockerfile.PROD"
    click Docker "https://github.com/reactplay/react-play/blob/main/docker-compose-dev.yml"
    click Docker "https://github.com/reactplay/react-play/blob/main/docker-compose-prod.yml"
    click Netlify "https://github.com/reactplay/react-play/blob/main/netlify.toml"
```
