# yurisldk/realworld-react-fsd architecture

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

- Interactive diagram: https://gitdiagram.com/yurisldk/realworld-react-fsd
- Repository: https://github.com/yurisldk/realworld-react-fsd

## Overview

1. **System boundary**
   This repository is a **frontend-only RealWorld/Medium clone**. The app runs in the browser as a React SPA, but it depends on an external **backend API at `/api`** for all domain data: users, articles, comments, profiles, favorites, and follows.

2. **Top-level architecture**
   The codebase is split into three main areas:
   - `src/app` for the application shell and root routing
   - `src/pages` for page-scoped route modules
   - `src/shared` for reusable API, router, test, and UI utilities  
   This is a page-oriented version of Feature-Sliced Design, with most business logic living close to each page route.

3. **Application shell**
   `src/app/index.tsx` and `src/app/browser-router.tsx` form the entry point and root router.  
   `src/app/app-layout.ui.tsx` provides the shared frame around pages, while `src/app/app.loader.ts` handles app-wide bootstrap concerns such as initial user loading.  
   `src/app/main.css` and `src/app/browser-router.tsx` define the global presentation and routing boundary.

4. **Routing model**
   Each page exposes a route module like `src/pages/home/home.route.ts` or `src/pages/article/article.route.ts`.  
   The README notes that these route modules are **lazy-loaded**, so the initial bundle only loads the shell and then fetches page code on demand.  
   Route modules typically bundle together:
   - page UI
   - route loader
   - route actions
   - page-specific state/helpers

5. **Data loading flow**
   Page data is fetched in **React Router loaders**, not directly in components.  
   Examples: `home.loader.ts`, `article.loader.ts`, `profile.loader.ts`, `settings.loader.ts`, `editor.loader.ts`.  
   These loaders are backed by **TanStack React Query**, which centralizes caching, request deduplication, and synchronization with mutations.

6. **Mutation flow**
   Writes are handled through **React Router actions** rather than ad hoc submit handlers.  
   Examples include:
   - article create/update/delete
   - comment create/delete
   - follow/unfollow
   - favorite/unfavorite
   - login/register/logout/update  
   This keeps mutation logic at the route boundary and makes form submission and navigation behavior consistent.

7. **Optimistic and interactive state**
   Some user interactions are implemented as **fetcher-driven optimistic updates**, especially:
   - favorite toggles
   - follow toggles  
   These appear in page-level action files such as `home/actions/article-favorite-toggle.action.ts` and `profile/actions/profile-follow-toggle.action.ts`, allowing UI updates to feel immediate while the backend request resolves.

8. **Authentication and route protection**
   Auth is treated as a cross-cutting routing concern in `src/shared/lib/react-router`.  
   Key helpers include:
   - `loadUserMiddleware.ts`
   - `requireAuthMiddleware.ts`
   - `redirectIfAuthenticatedMiddleware.ts`
   - `userContext.ts`  
   This means the route layer decides whether a user can enter a page, redirect them if needed, and expose the current user to the rest of the app.

9. **Shared API layer**
   `src/shared/api` contains the reusable transport and error-handling boundary:
   - `auth-fetch.ts` for authenticated requests
   - `auth-storage.ts` for token/session persistence
   - `handleApiError.ts` and `action-result.ts` for normalized failure handling
   - `queryClient.ts` for React Query configuration
   - `validateSchema.ts` for schema-driven validation  
   This is the main gateway between UI state and the backend API.

10. **Contract generation and validation**
    The project uses **OpenAPI + Orval** to generate client artifacts from `openapi.yaml` via `orval.config.ts`.  
    A local conversion step in `convert-zod-mini.ts` post-processes generated Zod schemas.  
    Architecturally, this means the frontend is tied to a formal backend contract, and request payloads are validated before mutations are sent.

11. **Page boundaries**
    Each feature area is isolated into its own page slice:
    - `home` for feeds and article lists
    - `article` for article detail, comments, and article actions
    - `editor` for create/update flows
    - `profile` for author profiles and authored/favorited feeds
    - `settings` for account management
    - `login` and `register` for auth entry points
    - `page-404` for unmatched routes  
    This separation is important for diagramming because page modules are the primary functional boundaries.

12. **Shared UI and utility components**
    `src/shared/ui` holds common visual building blocks such as:
    - spinner
    - async error card
    - error message list
    - global progress bar  
    These are reused across pages and support the app’s loading/error states without duplicating page-specific UI.

13. **Testing and development boundary**
    Tests use **Jest + Testing Library**, with `src/shared/lib/test/setup.ts` providing shared test setup.  
    `public/mockServiceWorker.js` indicates **MSW** support for mocking network calls in development or tests.  
    This creates a clear separation between UI behavior tests and the live backend API.

14. **Build and deployment**
    The app is bundled with **Webpack 5** and served in production through **nginx** inside a Docker image.  
    `docker-compose.yml`, `Dockerfile`, and `nginx.conf` define the runtime packaging path, while GitHub Actions workflows handle checks, builds, and releases.  
    For an architecture diagram, the important runtime flow is: browser → frontend bundle served by nginx → API calls to the external backend service.

Main entry points: [`src/app/browser-router.tsx`](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/app/browser-router.tsx) (Root router), [`src/shared/api`](https://github.com/yurisldk/realworld-react-fsd/tree/master/src/shared/api) (API layer), [`src/shared/lib/react-router`](https://github.com/yurisldk/realworld-react-fsd/tree/master/src/shared/lib/react-router) (Route auth), [`src/pages/home/home.route.ts`](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/home/home.route.ts) (Home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App shell"]
  node_node_app_index(("App entry<br/>react entry<br/>[index.tsx]"))
  node_node_app_router["Root router<br/>[browser-router.tsx]"]
  node_node_app_layout["App layout<br/>shell ui<br/>[app-layout.ui.tsx]"]
  node_node_app_loader["App bootstrap<br/>loader<br/>[app.loader.ts]"]
end

subgraph group_group_pages["Pages"]
  node_node_home["Home<br/>page slice<br/>[home.route.ts]"]
  node_node_article["Article<br/>page slice<br/>[article.route.ts]"]
  node_node_editor["Editor<br/>page slice<br/>[editor.route.ts]"]
  node_node_profile["Profile<br/>page slice<br/>[profile.route.ts]"]
  node_node_settings["Settings<br/>page slice<br/>[settings.route.ts]"]
  node_node_login["Login<br/>auth page<br/>[login.route.ts]"]
  node_node_register["Register<br/>auth page<br/>[register.route.ts]"]
  node_node_404["Not found<br/>fallback page<br/>[page-404.route.ts]"]
end

subgraph group_group_shared["Shared"]
  node_node_api[("API layer<br/>transport")]
  node_node_router_lib["Route auth<br/>routing helpers"]
  node_node_shared_ui["Shared UI<br/>ui kit"]
  node_node_test["Test setup<br/>test infra<br/>[setup.ts]"]
end

subgraph group_group_contract["Contract & build"]
  node_node_contract["API contract<br/>openapi/orval<br/>[openapi.yaml]"]
  node_node_convert["Zod convert<br/>schema transform"]
  node_node_build[("Bundle & deploy<br/>webpack/nginx<br/>[webpack.config.js]")]
end

node_node_app_index -->|"boots"| node_node_app_router
node_node_app_router -->|"loads user"| node_node_app_loader
node_node_app_router -->|"wraps"| node_node_app_layout
node_node_app_router -.->|"lazy route"| node_node_home
node_node_app_router -.->|"lazy route"| node_node_article
node_node_app_router -.->|"lazy route"| node_node_editor
node_node_app_router -.->|"lazy route"| node_node_profile
node_node_app_router -.->|"lazy route"| node_node_settings
node_node_app_router -.->|"lazy route"| node_node_login
node_node_app_router -.->|"lazy route"| node_node_register
node_node_app_router -->|"fallback"| node_node_404
node_node_home -->|"queries"| node_node_api
node_node_article -->|"queries"| node_node_api
node_node_editor -->|"mutates"| node_node_api
node_node_profile -->|"queries"| node_node_api
node_node_settings -->|"mutates"| node_node_api
node_node_login -->|"mutates"| node_node_api
node_node_register -->|"mutates"| node_node_api
node_node_home -->|"auth guard"| node_node_router_lib
node_node_article -->|"auth guard"| node_node_router_lib
node_node_editor -->|"auth guard"| node_node_router_lib
node_node_profile -->|"user context"| node_node_router_lib
node_node_shared_ui -->|"used by"| node_node_app_layout
node_node_test -.->|"covers"| node_node_shared_ui
node_node_contract -->|"feeds"| node_node_convert
node_node_contract -->|"validates"| node_node_api
node_node_build -->|"bundles"| node_node_app_index
node_node_build -->|"generates"| node_node_contract

click node_node_app_index "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/app/index.tsx"
click node_node_app_router "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/app/browser-router.tsx"
click node_node_app_layout "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/app/app-layout.ui.tsx"
click node_node_app_loader "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/app/app.loader.ts"
click node_node_home "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/home/home.route.ts"
click node_node_article "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/article/article.route.ts"
click node_node_editor "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/editor/editor.route.ts"
click node_node_profile "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/profile/profile.route.ts"
click node_node_settings "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/settings/settings.route.ts"
click node_node_login "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/login/login.route.ts"
click node_node_register "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/register/register.route.ts"
click node_node_404 "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/page-404/page-404.route.ts"
click node_node_api "https://github.com/yurisldk/realworld-react-fsd/tree/master/src/shared/api"
click node_node_router_lib "https://github.com/yurisldk/realworld-react-fsd/tree/master/src/shared/lib/react-router"
click node_node_shared_ui "https://github.com/yurisldk/realworld-react-fsd/tree/master/src/shared/ui"
click node_node_test "https://github.com/yurisldk/realworld-react-fsd/blob/master/src/shared/lib/test/setup.ts"
click node_node_contract "https://github.com/yurisldk/realworld-react-fsd/blob/master/openapi.yaml"
click node_node_convert "https://github.com/yurisldk/realworld-react-fsd/blob/master/convert-zod-mini.ts"
click node_node_build "https://github.com/yurisldk/realworld-react-fsd/blob/master/webpack.config.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_node_app_index,node_node_app_router,node_node_app_layout,node_node_app_loader toneBlue
class node_node_home,node_node_article,node_node_editor,node_node_profile,node_node_settings,node_node_login,node_node_register,node_node_404 toneAmber
class node_node_api,node_node_router_lib,node_node_shared_ui,node_node_test toneMint
class node_node_contract,node_node_convert,node_node_build toneRose
```

## Components

### App shell

Browser entrypoint, root router, layout, and bootstrap.

- [App entry](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/app/index.tsx): react entry · Starts the browser app and mounts the React SPA. · `src/app/index.tsx`
- [Root router](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/app/browser-router.tsx): router · Defines the top-level routing boundary and lazy page loading. · `src/app/browser-router.tsx`
- [App layout](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/app/app-layout.ui.tsx): shell ui · Shared frame and chrome around routed pages. · `src/app/app-layout.ui.tsx`
- [App bootstrap](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/app/app.loader.ts): loader · Performs app-wide initial loading, including user bootstrap. · `src/app/app.loader.ts`

### Pages

Route-scoped feature slices for the RealWorld app.

- [Home](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/home/home.route.ts): page slice · Feed and article list route module. · `src/pages/home/home.route.ts`
- [Article](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/article/article.route.ts): page slice · Article detail, comments, and article actions. · `src/pages/article/article.route.ts`
- [Editor](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/editor/editor.route.ts): page slice · Create and update article flows. · `src/pages/editor/editor.route.ts`
- [Profile](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/profile/profile.route.ts): page slice · Author profiles plus authored and favorited feeds. · `src/pages/profile/profile.route.ts`
- [Settings](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/settings/settings.route.ts): page slice · Account settings and session management. · `src/pages/settings/settings.route.ts`
- [Login](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/login/login.route.ts): auth page · User sign-in route. · `src/pages/login/login.route.ts`
- [Register](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/register/register.route.ts): auth page · User registration route. · `src/pages/register/register.route.ts`
- [Not found](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/pages/page-404/page-404.route.ts): fallback page · Unmatched route handling. · `src/pages/page-404/page-404.route.ts`

### Shared

Reusable API, routing, test, and UI infrastructure.

- [API layer](https://github.com/yurisldk/realworld-react-fsd/tree/master/src/shared/api): transport · Authenticated fetch, error normalization, validation, and query client setup. · `src/shared/api`
- [Route auth](https://github.com/yurisldk/realworld-react-fsd/tree/master/src/shared/lib/react-router): routing helpers · Middlewares and user context for auth-aware routing. · `src/shared/lib/react-router`
- [Shared UI](https://github.com/yurisldk/realworld-react-fsd/tree/master/src/shared/ui): ui kit · Reusable loading and error components. · `src/shared/ui`
- [Test setup](https://github.com/yurisldk/realworld-react-fsd/blob/master/src/shared/lib/test/setup.ts): test infra · Shared test harness and setup for UI tests. · `src/shared/lib/test/setup.ts`

### Contract & build

API contract generation, bundling, and deployment packaging.

- [API contract](https://github.com/yurisldk/realworld-react-fsd/blob/master/openapi.yaml): openapi/orval · OpenAPI source and generated client contract tooling. · `openapi.yaml`
- [Zod convert](https://github.com/yurisldk/realworld-react-fsd/blob/master/convert-zod-mini.ts): schema transform · Post-processes generated schemas for frontend validation. · `convert-zod-mini.ts`
- [Bundle & deploy](https://github.com/yurisldk/realworld-react-fsd/blob/master/webpack.config.js): webpack/nginx · Frontend bundling and production serving/package runtime. · `webpack.config.js`

## Connections

- App entry → Root router: boots · The app entry mounts the router boundary.
- Root router → App bootstrap: loads user · Root routing composes app bootstrap and user hydration.
- Root router → App layout: wraps · Pages render inside the shared application frame.
- Root router → Home: lazy route · Route modules are loaded on demand.
- Root router → Article: lazy route · Route modules are loaded on demand.
- Root router → Editor: lazy route · Route modules are loaded on demand.
- Root router → Profile: lazy route · Route modules are loaded on demand.
- Root router → Settings: lazy route · Route modules are loaded on demand.
- Root router → Login: lazy route · Route modules are loaded on demand.
- Root router → Register: lazy route · Route modules are loaded on demand.
- Root router → Not found: fallback · Unmatched routes resolve to the 404 page.
- Home → API layer: queries · Fetches feed data and article lists through the shared API boundary.
- Article → API layer: queries · Loads article detail, comments, and related data.
- Editor → API layer: mutates · Creates and updates articles through route actions.
- Profile → API layer: queries · Loads profile and feed data through the shared API boundary.
- Settings → API layer: mutates · Updates account data and logs users out.
- Login → API layer: mutates · Submits login credentials through route actions.
- Register → API layer: mutates · Submits registration data through route actions.
- Home → Route auth: auth guard · Route access and current-user state are mediated by shared router helpers.
- Article → Route auth: auth guard · Protected route behavior and user context flow through shared router helpers.
- Editor → Route auth: auth guard · Editor access is protected by route middleware.
- Profile → Route auth: user context · Profile interactions use shared router user context and guards.
- Shared UI → App layout: used by · Loading and error visuals support the shared app shell.
- Test setup → Shared UI: covers · Shared test setup exercises reusable UI components.
- API contract → Zod convert: feeds · Generated schemas are post-processed before use.
- API contract → API layer: validates · Contract artifacts shape request and response handling.
- Bundle & deploy → App entry: bundles · Webpack produces the browser deliverable from the app entry.
- Bundle & deploy → API contract: generates · The build pipeline is tied to the OpenAPI/Orval contract.
