# yukionishi1129/bulletproof-react architecture

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

- Interactive diagram: https://gitdiagram.com/yukionishi1129/bulletproof-react
- Repository: https://github.com/yukionishi1129/bulletproof-react

## Overview

##### Project Type and Purpose
- This is a front-end, single-page React application that serves as an opinionated, “bulletproof” architecture for production-ready React projects.
- It provides a scalable file structure, built-in patterns (features, API layer, state management, testing, styling), and example code for real-world use cases.
- There is no backend code here; instead, the app relies on external HTTP APIs (consumed via axios/react-query) and uses MSW (Mock Service Worker) for local testing.

##### High-Level Components
a. Public Layer
- `/public`: static assets (index.html, manifest.json, mockServiceWorker.js), redirects, robots.txt.
b. Application Shell
- `src/index.tsx` → initializes React, React-Query provider, custom providers (`src/providers/app.tsx`), global styles (`index.css`), and mounts `<App />`.
c. Core Providers & Config
- `src/providers`: top-level contexts (e.g., Theme, React-Query client).
- `craco.config.js` & `tailwind.config.js`: build tooling and styling.
d. Routing
- `src/routes`: defines public vs protected route sets.
- `<App />` (in `src/App.tsx`): wraps routes in layouts.
e. Feature Modules
- `src/features/<domain>`: each feature folder (auth, discussions, comments, users, teams, misc) contains:
- `api/*`: axios calls via `src/lib/axios.ts` + wrapped in React-Query hooks
- `components/*`: presentational or form UI
- `routes/*`: route components
- `types`: domain types
f. UI Components & Styling
- `src/components`: reusable UI elements (Buttons, Dialogs, Tables, Spinner, etc.) with Storybook stories.
g. State Management
- `src/stores`: lightweight Zustand stores (e.g., notifications).
- React-Query (`src/lib/react-query.ts`) for server state.
h. Utilities & Lib
- `src/lib`: auth helpers, authorization HOCs, axios instance, react-query config.
- `src/utils`: formatting, lazy imports, storage.
i. Testing
- Unit tests: `__tests__`, `cypress` for end-to-end, MSW mocks under `src/test/server`.
- CI workflow in `.github/workflows/ci.yml`.
j. Documentation
- `docs/`: markdown guidelines on architecture, styling, state management, API layer, error handling, deployment.

##### Relationships & Data Flow
1. User interacts with UI (Components in `src/components` or feature UIs).
2. Routed by React Router (`src/routes`) to a feature route.
3. Components trigger data fetching via React-Query hooks / Zustand actions.
4. React-Query uses `src/lib/axios.ts` to call external REST endpoints.
5. Responses update React-Query cache (server state) and/or Zustand stores (client state).
6. State changes re-render UI.
7. Notifications are managed by `stores/notifications.ts` and shown via `Notifications` component.
8. E2E tests in Cypress intercept network via MSW (`public/mockServiceWorker.js`) and validate flows.

##### Key Architectural Patterns
- Feature-based folder structure for domain isolation.
- Separation of concerns: UI components vs feature logic vs API.
- React-Query for async server state; Zustand for local/global client state.
- Pluggable component library (Atomic Elements, Forms).
- Storybook for visual component testing and documentation.
- MSW for reliable testing environment.
- CRACO for zero-eject configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Client
    Browser["Browser (Client)"]:::external

    %% Public Layer
    subgraph "Public Layer"
        PublicDir["public/"]:::config
        HTML["index.html"]:::config
        Manifest["manifest.json"]:::config
        MSWWorker["mockServiceWorker.js"]:::test
        Robots["robots.txt"]:::config
        Redirects["_redirects"]:::config
    end

    %% Application Shell
    subgraph "Application Shell"
        Index["src/index.tsx"]:::ui
        AppComp["src/App.tsx"]:::ui
        GlobalCSS["src/index.css"]:::ui
        AppProvider["src/providers/app.tsx"]:::ui
    end

    %% Core Providers & Config
    subgraph "Core Providers & Config"
        ProvidersDir["src/providers/"]:::state
        CRACO["craco.config.js"]:::config
        Tailwind["tailwind.config.js"]:::config
    end

    %% Routing
    subgraph "Routing"
        RoutesDir["src/routes/"]:::ui
        PublicRoutes["public.tsx"]:::ui
        ProtectedRoutes["protected.tsx"]:::ui
    end

    %% Feature Modules
    subgraph "Feature Modules"
        Auth["auth"]:::ui
        Disc["discussions"]:::ui
        Comm["comments"]:::ui
        Users["users"]:::ui
        Teams["teams"]:::ui
        Misc["misc"]:::ui
    end

    %% UI Components & Styling
    UI["src/components/"]:::ui

    %% State Management
    subgraph "State Management"
        ZustandNotif["src/stores/notifications.ts"]:::state
        ReactQueryCfg["src/lib/react-query.ts"]:::state
    end

    %% API Layer & Utilities
    subgraph "API Layer & Utilities"
        Axios["src/lib/axios.ts"]:::api
        AuthUtil["src/lib/auth.tsx"]:::api
        AuthZ["src/lib/authorization.tsx"]:::api
        UtilsDir["src/utils/"]:::api
    end

    %% External Services
    ExternalAPI["External REST API"]:::external

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        CypressDir["cypress/"]:::test
        MSWServer["src/test/server/"]:::test
        CIYaml[".github/workflows/ci.yml"]:::test
        SetupTests["src/setupTests.ts"]:::test
    end

    %% Documentation
    Docs["docs/"]:::config

    %% Relationships
    Browser -->|"loads index.html"| PublicDir
    Browser -->|"serves mock worker"| MSWWorker
    Browser -->|"> mount App"| Index
    Index -->|"initialize providers"| AppProvider
    AppProvider --> ProvidersDir
    AppProvider --> CRACO
    AppProvider --> Tailwind
    AppComp --> RoutesDir
    RoutesDir --> PublicRoutes
    RoutesDir --> ProtectedRoutes
    PublicRoutes --> Auth
    ProtectedRoutes --> Disc
    ProtectedRoutes --> Comm
    ProtectedRoutes --> Users
    ProtectedRoutes --> Teams
    ProtectedRoutes --> Misc

    Auth -->|"useQuery/getUser"| Axios
    Disc -->|"HTTP GET /discussions"| Axios
    Comm -->|"HTTP GET /comments"| Axios
    Users -->|"HTTP GET /users"| Axios
    Teams -->|"HTTP GET /teams"| Axios

    FeatureModulesAPIFeeds(( )):::api
    Axios -->|"> fetch"| ExternalAPI
    ExternalAPI -->|"> response"| ReactQueryCfg
    ReactQueryCfg -->|"invalidateQuery"| Disc
    ReactQueryCfg -->|"invalidateQuery"| Comm
    ReactQueryCfg -->|"invalidateQuery"| Users

    UI -->|"render components"| Auth
    UI -->|"render components"| Disc
    UI -->|"render components"| Comm

    ZustandNotif -->|"useStore.getState()"| Auth
    ZustandNotif -->|"useStore.getState()"| Disc

    AuthUtil --> Auth
    AuthZ --> Auth

    UtilsDir --> Auth
    UtilsDir --> UI

    CypressDir -->|"> run E2E"| MSWWorker
    MSWServer -->|"intercepts"| Axios
    CIYaml -->|"CI workflow"| CypressDir
    SetupTests -->|"unit tests"| Auth
    SetupTests -->|"unit tests"| UI

    Browser -.->|"> view Storybook"| UI

    Docs -->|"guides"| CRACO
    Docs -->|"guides"| Tailwind
    Docs -->|"guides"| ReactQueryCfg
    Docs -->|"guides"| ProvidersDir

    %% Click Events
    click PublicDir "https://github.com/yukionishi1129/bulletproof-react/tree/master/public/"
    click HTML "https://github.com/yukionishi1129/bulletproof-react/blob/master/public/index.html"
    click Manifest "https://github.com/yukionishi1129/bulletproof-react/blob/master/public/manifest.json"
    click MSWWorker "https://github.com/yukionishi1129/bulletproof-react/blob/master/public/mockServiceWorker.js"
    click Robots "https://github.com/yukionishi1129/bulletproof-react/blob/master/public/robots.txt"
    click Redirects "https://github.com/yukionishi1129/bulletproof-react/tree/master/public/_redirects"

    click Index "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/index.tsx"
    click AppComp "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/App.tsx"
    click GlobalCSS "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/index.css"
    click AppProvider "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/providers/app.tsx"

    click ProvidersDir "https://github.com/yukionishi1129/bulletproof-react/tree/master/src/providers/"
    click CRACO "https://github.com/yukionishi1129/bulletproof-react/blob/master/craco.config.js"
    click Tailwind "https://github.com/yukionishi1129/bulletproof-react/blob/master/tailwind.config.js"

    click RoutesDir "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/routes/index.tsx"
    click PublicRoutes "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/routes/public.tsx"
    click ProtectedRoutes "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/routes/protected.tsx"

    click Auth "https://github.com/yukionishi1129/bulletproof-react/tree/master/src/features/auth/"
    click Disc "https://github.com/yukionishi1129/bulletproof-react/tree/master/src/features/discussions/"
    click Comm "https://github.com/yukionishi1129/bulletproof-react/tree/master/src/features/comments/"
    click Users "https://github.com/yukionishi1129/bulletproof-react/tree/master/src/features/users/"
    click Teams "https://github.com/yukionishi1129/bulletproof-react/tree/master/src/features/teams/"
    click Misc "https://github.com/yukionishi1129/bulletproof-react/tree/master/src/features/misc/"

    click UI "https://github.com/yukionishi1129/bulletproof-react/tree/master/src/components/"

    click ZustandNotif "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/stores/notifications.ts"
    click ReactQueryCfg "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/lib/react-query.ts"

    click Axios "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/lib/axios.ts"
    click AuthUtil "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/lib/auth.tsx"
    click AuthZ "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/lib/authorization.tsx"
    click UtilsDir "https://github.com/yukionishi1129/bulletproof-react/tree/master/src/utils/"

    click CypressDir "https://github.com/yukionishi1129/bulletproof-react/tree/master/cypress/"
    click MSWServer "https://github.com/yukionishi1129/bulletproof-react/tree/master/src/test/server/"
    click CIYaml "https://github.com/yukionishi1129/bulletproof-react/blob/master/.github/workflows/ci.yml"
    click SetupTests "https://github.com/yukionishi1129/bulletproof-react/blob/master/src/setupTests.ts"

    click Docs "https://github.com/yukionishi1129/bulletproof-react/tree/master/docs/"

    %% Styles
    classDef ui fill:#eef,stroke:#88f,stroke-width:2px;
    classDef state fill:#efe,stroke:#2a2,stroke-width:2px;
    classDef api fill:#fee,stroke:#f44,stroke-width:2px;
    classDef test fill:#eee,stroke:#888,stroke-width:2px;
    classDef config fill:#f5f5f5,stroke:#aaa,stroke-width:2px;
    classDef external fill:#ffd,stroke:#dd0,stroke-width:2px,stroke-dasharray: 5 5;
```
