How yurisldk/realworld-react-fsd works
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: browser-router.tsx Root router · api API layer · react-router Route auth · home.route.ts Home
Components 19
App shell
Browser entrypoint, root router, layout, and bootstrap.
- App entry · Starts the browser app and mounts the React SPA.
src/app/index.tsx - Root router · Defines the top-level routing boundary and lazy page loading.
src/app/browser-router.tsx - App layout · Shared frame and chrome around routed pages.
src/app/app-layout.ui.tsx - App bootstrap · Performs app-wide initial loading, including user bootstrap.
src/app/app.loader.ts
Pages
Route-scoped feature slices for the RealWorld app.
- Home · Feed and article list route module.
src/pages/home/home.route.ts - Article · Article detail, comments, and article actions.
src/pages/article/article.route.ts - Editor · Create and update article flows.
src/pages/editor/editor.route.ts - Profile · Author profiles plus authored and favorited feeds.
src/pages/profile/profile.route.ts - Settings · Account settings and session management.
src/pages/settings/settings.route.ts - Login · User sign-in route.
src/pages/login/login.route.ts - Register · User registration route.
src/pages/register/register.route.ts - Not found · Unmatched route handling.
src/pages/page-404/page-404.route.ts
Shared
Reusable API, routing, test, and UI infrastructure.
- API layer · Authenticated fetch, error normalization, validation, and query client setup.
src/shared/api - Route auth · Middlewares and user context for auth-aware routing.
src/shared/lib/react-router - Shared UI · Reusable loading and error components.
src/shared/ui - Test setup · 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 · OpenAPI source and generated client contract tooling.
openapi.yaml - Zod convert · Post-processes generated schemas for frontend validation.
convert-zod-mini.ts - Bundle & deploy · Frontend bundling and production serving/package runtime.
webpack.config.js
Connections 28
- 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.